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/build.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 Build System</title>
    6   <meta name="author" content="FCM development team">
    7   <meta name="descriptions" content="User Guide - The Build 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 Build 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 Build System
    16   </address>
    17 
    18   <h1>The Build 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 Build 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 build system is deprecated. The documentation for the current
     40  build system can be found at <a href="make.html">FCM Make</a>.</em></p>
    1941
    2042  <p>The build system analyses the directory tree containing a set of source
    21   code, processes the configuration, and invokes <em>make</em> to compile/build
    22   the source code into the project executables. In this chapter, we shall use
    23   many examples to explain how to use the build system. At the end of this
    24   chapter, you should be able to use the build system, either by defining the
    25   build configuration file directly or by using the extract system to generate
    26   a suitable build configuration file.</p>
    27 
    28   <h2><a name="command">The Build Command</a></h2>
     43  code, processes the configuration, and invokes <code>make</code> to
     44  compile/build the source code into the project executables. In this chapter,
     45  we shall use many examples to explain how to use the build system. At the end
     46  of this chapter, you should be able to use the build system, either by
     47  defining the build configuration file directly or by using the extract system
     48  to generate a suitable build configuration file.</p>
     49
     50  <h2 id="command">The Build Command</h2>
    2951
    3052  <p>To invoke the build system, simply issue the command:</p>
    … …  
    3456
    3557  <p>By default, the build system searches for a build configuration file
    36   "bld.cfg" in "$PWD" and then "$PWD/cfg". If a build configuration file is
    37   not found in these directories, the command fails with an error. If a build
    38   configuration file is found, the system will use the configuration specified
    39   in the file to perform the build. If you use the extract system to extract
    40   your source tree, a build configuration should be written for you
    41   automatically at the "cfg/" sub-directory of the destination root
    42   directory.</p>
     58  <samp>bld.cfg</samp> in <samp>$PWD</samp> and then <samp>$PWD/cfg</samp>. If
     59  a build configuration file is not found in these directories, the command
     60  fails with an error. If a build configuration file is found, the system will
     61  use the configuration specified in the file to perform the build. If you use
     62  the extract system to extract your source tree, a build configuration should
     63  be written for you automatically at the <samp>cfg/</samp> sub-directory of
     64  the destination root directory.</p>
    4365
    4466  <p>If the root directory of the build does not exist, the system performs a
    … …  
    4668  directory, the system performs an incremental build. If a full (fresh) build
    4769  is required for whatever reason, you can invoke the build system using the
    48   "-f" option, (i.e. the command becomes "fcm build -f").</p>
    49 
    50   <p>The build system uses GNU <em>make</em> to perform the majority of the
    51   build. GNU <em>make</em> has a "-j &lt;jobs&gt;" option to specify the
    52   number of &lt;jobs&gt; to run simultaneously. Invoking the build system with
    53   the same option triggers this option when the build system invokes the
    54   <em>make</em> command. The argument to the option &lt;jobs&gt; must be an
    55   integer. The default is 1. For example, the command "fcm build -j 4"
    56   will allow <em>make</em> to perform 4 jobs simultaneously.</p>
     70  <code>-f</code> option, (i.e. the command becomes <code>fcm build -f</code>).
     71  If you simply want to remove all the items generated by a previous build in
     72  the destination, you can invoke the build system using the
     73  <code>--clean</code> option.</p>
     74
     75  <p>The build system uses GNU <code>make</code> to perform the majority of the
     76  build. GNU <code>make</code> has a <code>-j jobs</code> option to specify the
     77  number of <var>jobs</var> to run simultaneously. Invoking the build system
     78  with the same option triggers this option when the build system invokes the
     79  <code>make</code> command. The argument to the option <var>jobs</var> must be
     80  an integer. The default is <samp>1</samp>. For example, the command <code>fcm
     81  build -j 4</code> will allow <code>make</code> to perform 4 jobs
     82  simultaneously.</p>
    5783
    5884  <p>For further information on the build command, please see <a href=
    59   "command_ref.html#fcm_bld">FCM Command Reference &gt; fcm build</a>.</p>
    60 
    61   <h2><a name="basic">Basic Features</a></h2>
     85  "command_ref.html#fcm-build">FCM Command Reference &gt; fcm build</a>.</p>
     86
     87  <h2 id="basic">Basic Features</h2>
    6288
    6389  <p>The build configuration file is the user interface of the build system. It
    6490  is a line based text file. You can create your own build configuration file
    65   or you can use the extract system to create one for you.  For a complete set
    66   of build configuration file declarations, please refer to the <a
    67   href="annex_bld_cfg.html">Annex: Declarations in FCM build configuration
     91  or you can use the extract system to create one for you. For a complete set
     92  of build configuration file declarations, please refer to the <a href=
     93  "annex_bld_cfg.html">Annex: Declarations in FCM build configuration
    6894  file</a>.</p>
    6995
    70   <h3><a name="basic_build">Basic build configuration</a></h3>
    71 
    72   <p>Suppose we have a directory at "$HOME/example". Its sub-directory
    73   at "$HOME/example/src" contains a source tree to be built. You may
    74   want to have a build configuration file "$HOME/example/cfg/bld.cfg",
    75   which may contain:</p>
    76 
    77   <table class="pad" summary="build_example1" border="1" width="100%">
    78     <tr>
    79       <th>Build configuration example 1 - basic build configuration</th>
    80     </tr>
    81 
    82     <tr>
    83       <td>
    84         <pre>
     96  <h3 id="basic_build">Basic build configuration</h3>
     97
     98  <p>Suppose we have a directory at <samp>$HOME/example</samp>. Its
     99  sub-directory at <samp>$HOME/example/src</samp> contains a source tree to be
     100  built. You may want to have a build configuration file
     101  <samp>$HOME/example/cfg/bld.cfg</samp>, which may contain:</p>
     102  <pre id="example_1">
     103# Example 1
     104# ----------------------------------------------------------------------
    85105cfg::type     bld                           # line 1
    86106cfg::version  1.0                           # line 2
    87107
    88 dir::root     $HOME/example                 # line 4
     108dest          $HOME/example                 # line 4
    89109
    90110target        foo.exe bar.exe               # line 6
    91111
    92 tool::fc      ifc                           # line 8
     112tool::fc      ifort                         # line 8
    93113tool::fflags  -O3                           # line 9
    94114tool::cc      gcc                           # line 10
    95115tool::cflags  -O3                           # line 11
    96 tool::ld      ifc                           # line 12
     116
    97117tool::ldflags -O3 -L$(HOME)/lib -legg -lham # line 13
    98118</pre>
    99       </td>
    100     </tr>
    101   </table>
    102119
    103120  <p>Here is an explanation of what each line does:</p>
    104121
    105122  <ul>
    106     <li>line 1: the label CFG::TYPE declares the type of the configuration
    107     file. The value "bld" tells the system that it is a build configuration
    108     file.</li>
    109 
    110     <li>line 2: the label CFG::VERSION declares the version of the build
    111     configuration file. The current default is "1.0". Although it is not
    112     currently used, if we have to change the format of the configuration file
    113     at a later stage, we shall be able to use this number to determine whether
    114     we are reading a file with an older format or one with a newer
    115     format.</li>
    116 
    117     <li>line 4: the label DIR::ROOT declares the root directory of the current
    118     build.</li>
    119 
    120     <li>line 6: the label TARGET declares a list of "default" targets. The
    121     default targets of the current build will be "foo.exe" and "bar.exe".</li>
    122 
    123     <li>line 8: the label TOOL::FC declares the Fortran compiler command.</li>
    124 
    125     <li>line 9: the label TOOL::FFLAGS declares the options to be used when
    126     invoking the Fortran compiler command.</li>
    127 
    128     <li>line 10: the label TOOL::CC declares the C compiler command.</li>
    129 
    130     <li>line 11: the label TOOL::CFLAGS declares the options to be used when
    131     invoking the C compiler command.</li>
    132 
    133     <li>line 12: the label TOOL::LD declares the linker command.</li>
    134 
    135     <li>line 13: the label TOOL::LDFLAGS declares the options to be used when
    136     invoking the linker command.</li>
     123    <li><dfn>line 1</dfn>: the label <code>CFG::TYPE</code> declares the type
     124    of the configuration file. The value <samp>bld</samp> tells the system that
     125    it is a build configuration file.</li>
     126
     127    <li><dfn>line 2</dfn>: the label <code>CFG::VERSION</code> declares the
     128    version of the build configuration file. The current default is
     129    <samp>1.0</samp>. Although it is not currently used, if we have to change
     130    the format of the configuration file at a later stage, we shall be able to
     131    use this number to determine whether we are reading a file with an older
     132    format or one with a newer format.</li>
     133
     134    <li><dfn>line 4</dfn>: the label <code>DEST</code> declares the root
     135    directory of the current build.</li>
     136
     137    <li><dfn>line 6</dfn>: the label <code>TARGET</code> declares a list of
     138    <em>default</em> targets. The default targets of the current build will be
     139    <samp>foo.exe</samp> and <samp>bar.exe</samp>.</li>
     140
     141    <li><dfn>line 8</dfn>: the label <code>TOOL::FC</code> declares the Fortran
     142    compiler command.</li>
     143
     144    <li><dfn>line 9</dfn>: the label <code>TOOL::FFLAGS</code> declares the
     145    options to be used when invoking the Fortran compiler command.</li>
     146
     147    <li><dfn>line 10</dfn>: the label <code>TOOL::CC</code> declares the C
     148    compiler command.</li>
     149
     150    <li><dfn>line 11</dfn>: the label <code>TOOL::CFLAGS</code> declares the
     151    options to be used when invoking the C compiler command.</li>
     152
     153    <li><dfn>line 13</dfn>: the label <code>TOOL::LDFLAGS</code> declares the
     154    options to be used when invoking the linker command.</li>
    137155  </ul>
    138156
    139   <p>When we invoke the build system, it reads the above configuration file.  It
    140   will go through various internal processes, such as dependency generations, to
    141   obtain the required information to prepare the <em>Makefile</em> of the build.
    142   (All of which will be described in later sections.) The <em>Makefile</em> of
    143   the build will be placed at "$HOME/example/bld". The system will then invoke
    144   <em>make</em> to build the targets specified in line 6, i.e. "foo.exe" and
    145   "bar.exe" using the build tools specified between line 8 to line 13. On a
    146   successful build, the target executables will be sent to "$HOME/example/bin/".
    147   The build system also creates a shell script called "fcm_env.ksh" in
    148   "$HOME/example/". If you source the shell script, it will export your PATH
    149   environment variable to search the "$HOME/example/bin/" directory for
    150   executables.</p>
    151 
    152   <p>N.B. You may have noticed that the "-c" (compile to object file only)
    153   option is missing from the compiler flags declarations. This is because the
    154   option is inserted automatically by the build system, unless it is already
    155   declared.</p>
    156 
    157   <table class="pad" summary=
    158   "note - declaration of source directories for build" border="1" width="100%">
    159     <tr>
    160       <th>Note - declaration of source directories for build</th>
    161     </tr>
    162 
    163     <tr>
    164       <td>
    165         Source directories do not have to reside in the source sub-directory
    166         of the build root directory. They can be anywhere, but you will have to
    167         declare them individually, using the label SRC::&lt;pcks&gt;, where
    168         &lt;pcks&gt; is the sub-package name in which the source directory
    169         belongs. E.g.
    170 
    171         <pre>
    172 # Declare a source directory in the sub-package "foo::bar"
    173 src::foo::bar  $HOME/foo/bar
    174 </pre>
    175 
    176         <p>By default, the build system searches the "src/"
    177         sub-directory of the build root directory for sub-package source
    178         directories. If all source directories are already declared
    179         explicitly, you can switch off the automatic directory search by
    180         setting the SEARCH_SRC flag to 0. E.g.</p>
    181 
    182         <pre>
    183 search_src  0
    184 </pre>
    185 
    186         <p>As mentioned in the previous chapter, the name of a sub-package
    187         &lt;pcks&gt; provides a unique namespace for a file container. The
    188         name of a sub-package is a list of words delimited by the double
    189         colons "::", which is turned into the double underscores "__" by
    190         the build system internally. Please avoid using "::" and "__" for
    191         naming your files and directories.</p>
    192        
    193         <p>In the build system, the sub-package name also provides an
    194         "inheritance" relationship for sub-packages. For instance, we may
    195         have a sub-package called "foo::bar::egg", which belongs to the
    196         sub-package "foo::bar", which belongs to the package "foo".</p>
    197        
    198         <ul>
    199           <li>If we declare a global build tool, it applies to all
    200           packages.</li>
    201          
    202           <li>If we declare a build tool for "foo", it applies also to the
    203           sub-package "foo::bar" and "foo::bar::egg".</li>
    204          
    205           <li>If we declare a build tool for "foo::bar", it applies also to
    206           "foo::bar::egg", but not to other sub-packages in "foo".</li>
    207         </ul>
    208       </td>
    209     </tr>
    210   </table>
    211 
    212   <h3><a name="basic_extract">Build configuration via the extract
    213   system</a></h3>
     157  <p>When we invoke the build system, it reads the above configuration file. It
     158  will go through various internal processes, such as dependency generations,
     159  to obtain the required information to prepare the <samp>Makefile</samp> of
     160  the build. (All of which will be described in later sections.) The
     161  <samp>Makefile</samp> of the build will be placed at
     162  <samp>$HOME/example/bld</samp>. The system will then invoke <code>make</code>
     163  to build the targets specified in line 6, i.e. <samp>foo.exe</samp> and
     164  <samp>bar.exe</samp> using the build tools specified between line 8 to line
     165  13. On a successful build, the target executables will be sent to
     166  <samp>$HOME/example/bin/</samp>. The build system also creates a shell script
     167  called <samp>fcm_env.sh</samp> in <samp>$HOME/example/</samp>. If you source
     168  the shell script, it will export your <var>PATH</var> environment variable to
     169  search the <samp>$HOME/example/bin/</samp> directory for executables.</p>
     170
     171  <p>N.B. You may have noticed that the <code>-c</code> (compile to object file
     172  only) option is missing from the compiler flags declarations. This is because
     173  the option is inserted automatically by the build system, unless it is
     174  already declared.</p>
     175
     176  <p>N.B. You can declare the linker using <code>TOOL::LD</code>. If it is not
     177  specified, the default is to use the compiler command for the source file
     178  containing the main program.</p>
     179
     180  <dl>
     181    <dt>Note - declaration of source files for build</dt>
     182
     183    <dd>
     184      <p>Source files do not have to reside in the <samp>src/</samp>
     185      sub-directory of the build root directory. They can be anywhere, but you
     186      will have to declare them using the label <code>SRC::&lt;pcks&gt;</code>,
     187      where <code>&lt;pcks&gt;</code> is the sub-package name in which the
     188      source belongs. If a directory is specified then the build system
     189      automatically searches for all source files in this directory. E.g.</p>
     190      <pre>
     191# Declare a source in the sub-package "foo/bar"
     192src::foo/bar  $HOME/foo/bar
     193</pre>
     194
     195      <p>By default, the build system searches the <samp>src/</samp>
     196      sub-directory of the build root directory for source files. If all source
     197      files are already declared explicitly, you can switch off the automatic
     198      directory search by setting the <code>SEARCH_SRC</code> flag to false.
     199      E.g.</p>
     200      <pre>
     201search_src  false
     202</pre>
     203
     204      <p>As mentioned in the previous chapter, the name of a sub-package
     205      &lt;pcks&gt; provides a unique namespace for a file. The name of a
     206      sub-package is a list of words delimited by a slash <code>/</code>. (The
     207      system uses the double colons <code>::</code> and the double underscores
     208      <code>__</code> internally. Please avoid using <code>::</code> and
     209      <code>__</code> for naming your files and directories.)</p>
     210
     211      <p>Currently, the build system only supports non-space characters in the
     212      package name, as the space character is used as a delimiter between the
     213      declaration label and its value. If there are spaces in the path name to
     214      a file or directory, you should explicity re-define the package name of
     215      that path to a package name with no space using the above method.
     216      However, we recommend that only non-space characters are used for naming
     217      directories and files to make life simple.</p>
     218
     219      <p>In the build system, the sub-package name also provides an
     220      <em>inheritance</em> relationship for sub-packages. For instance, we may
     221      have a sub-package called <samp>foo/bar/egg</samp>, which belongs to the
     222      sub-package <samp>foo/bar</samp>, which belongs to the package
     223      <samp>foo</samp>.</p>
     224
     225      <ul>
     226        <li>If we declare a global build tool, it applies to all packages.</li>
     227
     228        <li>If we declare a build tool for <samp>foo</samp>, it applies also to
     229        the sub-package <samp>foo/bar</samp> and <samp>foo/bar/egg</samp>.</li>
     230
     231        <li>If we declare a build tool for <samp>foo/bar</samp>, it applies
     232        also to <samp>foo/bar/egg</samp>, but not to other sub-packages in
     233        <samp>foo</samp>.</li>
     234      </ul>
     235    </dd>
     236  </dl>
     237
     238  <h3 id="basic_extract">Build configuration via the extract system</h3>
    214239
    215240  <p>As mentioned earlier, you can obtain a build configuration file through
    216241  the extract system. The following example is what you may have in your
    217   extract configuration in order to obtain a similar configuration as example
    218   1:</p>
    219 
    220   <table class="pad" summary="build_example2" border="1" width="100%">
    221     <tr>
    222       <th>Build configuration example 2 - created by the extract system</th>
    223     </tr>
    224 
    225     <tr>
    226       <td>
    227         <pre>
     242  extract configuration in order to obtain a similar configuration as <a href=
     243  "#example_1">example 1</a>:</p>
     244  <pre id="example_2">
     245# Example 2
     246# ----------------------------------------------------------------------
    228247cfg::type          ext                           # line 1
    229248cfg::version       1.0                           # line 2
    230249
    231 dest::rootdir      $HOME/example                 # line 4
     250dest               $HOME/example                 # line 4
    232251
    233252bld::target        foo.exe bar.exe               # line 6
    234253
    235 bld::tool::fc      ifc                           # line 8
     254bld::tool::fc      ifort                         # line 8
    236255bld::tool::fflags  -O3                           # line 9
    237256bld::tool::cc      gcc                           # line 10
    238257bld::tool::cflags  -O3                           # line 11
    239 bld::tool::ld      ifc                           # line 12
     258
    240259bld::tool::ldflags -O3 -L$(HOME)/lib -legg -lham # line 13
    241260
    242 # ... and other declarations for repositories and source directories ...
    243 </pre>
    244       </td>
    245     </tr>
    246   </table>
    247 
    248   <p>It is easy to note the similarities and differences between example 1 and
    249   example 2. Example 2 is an extract configuration file. It extracts to a
     261# ... and other declarations for source locations ...
     262</pre>
     263
     264  <p>It is easy to note the similarities and differences between <a href=
     265  "#example_1">example 1</a> and <a href="#example_2">example 2</a>. <a href=
     266  "#example_2">Example 2</a> is an extract configuration file. It extracts to a
    250267  destination root directory that will become the root directory of the build.
    251268  Line 6 to line 13 are the same declarations, except that they are now
    252   prefixed with "BLD::". In an extract configuration file, any lines prefixed
    253   with "BLD::" means that they are build configuration setting. These lines
    254   are "ignored" by the extract system but are parsed down to the output build
    255   configuration file, with the "BLD::" prefix removed. (Note: the "BLD::" prefix
    256   is optional for declarations in a build configuration file.)</p>
    257 
    258   <p>N.B. If you use the extract system to mirror an extraction to a remote
    259   machine, the extract system will assume that the root directory of the
    260   remote destination is the root directory of the build, and that the build
    261   will be carried out in the remote machine.</p>
    262 
    263   <h3><a name="basic_exename">Naming of executables</a></h3>
    264 
    265   <p>If a source file called "foo.f90" contains a main program, the default
    266   behaviour of the system is to name its executable "foo.exe". The root name of
    267   the executable is the same as the original file name, but its file extension
    268   is replaced with ".exe". The output extension can be altered by re-registering
    269   the extension for output EXE files. How this can be done will be discussed
    270   later in the sub-section <a href="#advanced_file-type">File Type</a>.</p>
    271  
     269  prefixed with <code>BLD::</code>. In an extract configuration file, any lines
     270  prefixed with <code>BLD::</code> means that they are build configuration
     271  setting. These lines are ignored by the extract system but are parsed down to
     272  the output build configuration file, with the <code>BLD::</code> prefix
     273  removed. (Note: the <code>BLD::</code> prefix is optional for declarations in
     274  a build configuration file.)</p>
     275
     276  <p>N.B. If you use the extract system to mirror an extract to an alternate
     277  location, the extract system will assume that the root directory of the
     278  alternate destination is the root directory of the build, and that the build
     279  will be carried out in that destination.</p>
     280
     281  <h3 id="basic_exename">Naming of executables</h3>
     282
     283  <p>If a source file called <samp>foo.f90</samp> contains a main program, the
     284  default behaviour of the system is to name its executable
     285  <samp>foo.exe</samp>. The root name of the executable is the same as the
     286  original file name, but its file extension is replaced with
     287  <samp>.exe</samp>. The output extension can be altered by re-registering the
     288  extension for output EXE files. How this can be done will be discussed later
     289  in the sub-section <a href="#advanced_file-type">File Type</a>.</p>
     290
    272291  <p>If you need to alter the full name of the executable, you can use the
    273   "EXE_NAME::" declaration. For example, the declaration:</p>
    274 
     292  <code>EXE_NAME::</code> declaration. For example, the declaration:</p>
    275293  <pre>
    276294bld::exe_name::foo  bar
    277295</pre>
    278296
    279   <p>will rename the executable of "foo.f90" from "foo.exe" to "bar".</p>
    280 
    281   <p>Note: the declaration label is "bld::exe_name::foo" (not
    282   "bld::exe_name::foo.exe") and the executable will be named "bar" (not
    283   "bar.exe").</p>
    284  
    285   <p>Another way to alter the full name of the executable is to use the package
    286   configuration file, which will be discussed later in the sub-section <a
    287   href="#other_pckcfg">Using a package configuration file</a>.</p>
    288 
    289   <h3><a name="basic_flags">Setting the compiler flags</a></h3>
     297  <p>will rename the executable of <samp>foo.f90</samp> from
     298  <samp>foo.exe</samp> to <samp>bar</samp>.</p>
     299
     300  <p>Note: the declaration label is <code>bld::exe_name::foo</code> (not
     301  <code>bld::exe_name::foo.exe</code>) and the executable will be named
     302  <samp>bar</samp> (not <samp>bar.exe</samp>).</p>
     303
     304  <h3 id="basic_flags">Setting the compiler flags</h3>
    290305
    291306  <p>As discussed in the first example, the compiler commands and their flags
    292   can be set via the "TOOL::" declarations. A simple "TOOL::FFLAGS"
    293   declaration, for example, alters the compiler options for compiling all
    294   Fortran source files in the build. If you need to alter the compiler options
    295   only for the source files in a particular sub-package, it is possible to do so
    296   by adding the sub-package name to the declaration label. For example, the
    297   declaration label "TOOL::FFLAGS::ops::code::OpsMod_Control" will ensure that
    298   the declaration only applies to the code in the sub-package
    299   "ops::code::OpsMod_Control". You can even make declarations down to the
    300   individual source file level. For example, the declaration label
    301   "TOOL::FFLAGS::ops::code::OpsMod_Control::Ops_Switch" will ensure that the
    302   declaration applies only for the file "Ops_Switch.f90".</p>
    303  
    304   <p>N.B. Although the prefix "TOOL::" and the tool names are
     307  can be set via the <code>TOOL::</code> declarations. A simple
     308  <code>TOOL::FFLAGS</code> declaration, for example, alters the compiler
     309  options for compiling all Fortran source files in the build. If you need to
     310  alter the compiler options only for the source files in a particular
     311  sub-package, it is possible to do so by adding the sub-package name to the
     312  declaration label. For example, the declaration label
     313  <code>TOOL::FFLAGS::foo/bar</code> will ensure that the declaration only
     314  applies to the code in the sub-package <samp>foo/bar</samp>. You can even
     315  make declarations down to the individual source file level. For example, the
     316  declaration label <code>TOOL::FFLAGS::foo/bar/egg.f90</code> will ensure that
     317  the declaration applies only for the file <samp>foo/bar/egg.f90</samp>.</p>
     318
     319  <p>N.B. Although the prefix <code>TOOL::</code> and the tool names are
    305320  case-insensitive, sub-package names are case sensitive in the declarations.
    306321  Internally, tool names are turned into uppercase, and the sub-package
    307   delimiters are changed from the double colons "::" to the double underscores
    308   "__". When the system generates the <em>Makefile</em> for the build, each
    309   "TOOL" declaration will be exported as an environment variable. For example,
    310   the declaration "tool::fflags::ops::code::OpsMod_Control" will be exported
    311   as "FFLAGS__ops__code__OpsMod_Control".</p>
    312 
    313   <p>N.B. TOOL declarations for sub-packages are only accepted by the system
    314   when it is sensible to do so. For example, it allows you to declare different
    315   compiler flags, linker commands and linker flags for different sub-packages,
    316   but it does not accept different compilers for different sub-packages.</p>
    317 
    318   <!--table class="pad" summary="note - TOOL declarations" border="1"
    319   width="100%">
    320     <tr>
    321       <th>Note - TOOL declarations</th>
    322     </tr>
    323 
    324     <tr>
    325       <td>The system does not stop you from making TOOL declarations that are
    326       not supported, but it will only use the ones that are supported. For
    327       example, you can define a compiler command for a sub-package, but it
    328       will be ignored.</td>
    329     </tr>
    330   </table-->
    331 
    332   <p>The following is an example setting in an extract configuration file
    333   based on example 2:</p>
    334 
    335   <table class="pad" summary="build_example3" border="1" width="100%">
    336     <tr>
    337       <th>Build configuration example 3 - compiler flags for different
    338       sub-packages</th>
    339     </tr>
    340 
    341     <tr>
    342       <td>
    343         <pre>
     322  delimiters are changed from the slash <code>/</code> (or double colons
     323  <code>::</code>) to the double underscores <code>__</code>. When the system
     324  generates the <samp>Makefile</samp> for the build, each <code>TOOL</code>
     325  declaration will be exported as an environment variable. For example, the
     326  declaration <code>tool::fflags/foo/bar</code> will be exported as
     327  <samp>FFLAGS__foo__bar</samp>.</p>
     328
     329  <p>N.B. <code>TOOL</code> declarations for sub-packages are only accepted by
     330  the system when it is sensible to do so. For example, it allows you to
     331  declare different compiler flags, linker commands and linker flags for
     332  different sub-packages, but it does not accept different compilers for
     333  different sub-packages. If you attempt to make a <code>TOOL</code>
     334  declaration for a sub-package that does not exist, the build system will exit
     335  with an error.</p>
     336
     337  <p>The following is an example setting in an extract configuration file based
     338  on <a href="#example_2">example 2</a>:</p>
     339  <pre id="example_3">
     340# Example 3
     341# ----------------------------------------------------------------------
    344342cfg::type              ext
    345343cfg::version           1.0
    346344
    347 dest::rootdir          $HOME/example
     345dest                   $HOME/example
    348346
    349347bld::target            foo.exe bar.exe
    350348
    351 bld::tool::fc          ifc
     349bld::tool::fc          ifort
    352350bld::tool::fflags      -O3    # line 9
    353351bld::tool::cc          gcc
    354352bld::tool::cflags      -O3
    355 bld::tool::ld          ifc
     353
    356354bld::tool::ldflags     -L$(HOME)/lib -legg -lham
    357355
    … …  
    361359# ... and other declarations for repositories and source directories ...
    362360</pre>
    363       </td>
    364     </tr>
    365   </table>
    366 
    367   <p>In the example above, line 15 alters the Fortran compiler flags for "ops",
    368   so that all source files in "ops" will be compiled with optimisation level
    369   1 and will have runtime error checking switched on. Line 16, alters the
    370   Fortran compiler flags for "gen", so that all source files in "gen" will be
    371   compiled with optimisation level 2. All other Fortran source files will use
    372   the global setting declared at line 9, so they they will all be compiled
    373   with optimisation level 3.</p>
    374 
    375   <table class="pad" summary=
    376   "note - changing compiler flags in incremental builds" border="1"
    377   width="100%">
    378     <tr>
    379       <th>Note - changing compiler flags in incremental builds</th>
    380     </tr>
    381 
    382     <tr>
    383       <td>
    384         Suppose you have performed a successful build using the configuration
    385         in example 3, and you have decided to change some of the compiler
    386         flags, you can do so by altering the appropriate flags in the build
    387         configuration file.  When you trigger an incremental build, the system
    388         will detect changes in compiler flags automatically, and update only
    389         the required targets. The following hierarchy is followed:
    390 
    391         <ul>
    392           <li>If the compiler flags for a particular source file change, only
    393           that source file and any targets depending on that source file are
    394           re-built.</li>
    395 
    396           <li>If the compiler flags for a particular sub-package change, only
    397           source files within that sub-package and any targets depending on
    398           those source files are re-built.</li>
    399 
    400           <li>If the global compiler flags change, all source files are
    401           re-built.</li>
    402 
    403           <li>If the compiler command changes, all source files are
    404           re-built.</li>
    405         </ul>
    406 
    407         <!--p>The build system implements the above hierarchy using a "flags"
    408         file system, which are dummy files created in the "flags/"
    409         sub-directory of the build root. They are updated by the "touch"
    410         command. The following dependencies are followed:</p>
    411 
    412         <ul>
    413           <li>Source files are dependent on its own "flags" file. E.g. the file
    414           Ops_Switch in sub-package ":ops::code::OpsMod_Control" is dependent
    415           on "FFLAGS__ops__code__OpsMod_Control__Ops_Switch.flags".</li>
    416 
    417           <li>The "flags" file of a source file is dependent on the "flags" file
    418           of its container sub-package. E.g. the above flags file is dependent
    419           on "FFLAGS__ops__code__OpsMod_Control.flags".</li>
    420 
    421           <li>The "flags" file of a sub-package is dependent on the "flags"
    422           file of its container sub-package. E.g. the above is dependent on
    423           "FFLAGS__ops__code.flags", which is dependent on
    424           "FFLAGS__ops.flags".</li>
    425 
    426           <li>The "flags" file of a top-level package is dependent on the
    427           "flags" file of the global flags. E.g. "FFLAGS__ops.flags" is
    428           dependent on "FFLAGS.flags".</li>
    429 
    430           <li>The "flags" file of the global "flags" file is dependent on the
    431           "flags" file of the compiler command. E.g. "FFLAGS.flags" is
    432           dependent on "FC.flags".</li>
    433         </ul>
    434        
    435         <p>The system records changes in declared tools using a cache file,
    436         (called ".bld_tool", located at the ".cache/" sub-directory of the
    437         built root). It is basically a list of "TOOL::" declarations for the
    438         latest build.  When an incremental build is invoked, the list is
    439         compared against the current set. If there are changes (modification,
    440         addition and deletion) in any declarations, the timestamp of the
    441         corresponding "flags" files will be updated. Files depending on the
    442         updated "flags" file will then be considered out of date by
    443         <em>make</em>, triggering a re-build of those files.</p-->
    444       </td>
    445     </tr>
    446   </table>
    447 
    448   <p>N.B. For a full list of build tools declarations, please see <a
    449   href="annex_bld_cfg.html#tools-list">Annex: Declarations in FCM build
     361
     362  <p>In the example above, line 15 alters the Fortran compiler flags for
     363  <samp>ops</samp>, so that all source files in <samp>ops</samp> will be
     364  compiled with optimisation level 1 and will have runtime error checking
     365  switched on. Line 16, alters the Fortran compiler flags for <samp>gen</samp>,
     366  so that all source files in <samp>gen</samp> will be compiled with
     367  optimisation level 2. All other Fortran source files will use the global
     368  setting declared at line 9, so they they will all be compiled with
     369  optimisation level 3.</p>
     370
     371  <dl>
     372    <dt>Note - changing compiler flags in incremental builds</dt>
     373
     374    <dd>
     375      <p>Suppose you have performed a successful build using the configuration
     376      in <a href="#example_3">example 3</a>, and you have decided to change
     377      some of the compiler flags, you can do so by altering the appropriate
     378      flags in the build configuration file. When you trigger an incremental
     379      build, the system will detect changes in compiler flags automatically,
     380      and update only the required targets. The following hierarchy is
     381      followed:</p>
     382
     383      <ul>
     384        <li>If the compiler flags for a particular source file change, only
     385        that source file and any targets depending on that source file are
     386        re-built.</li>
     387
     388        <li>If the compiler flags for a container package change, only source
     389        files within that container package and any targets depending on those
     390        source files are re-built.</li>
     391
     392        <li>If the global compiler flags change, all source files are
     393        re-built.</li>
     394
     395        <li>If the compiler command changes, all source files are
     396        re-built.</li>
     397      </ul>
     398    </dd>
     399  </dl>
     400
     401  <p>N.B. For a full list of build tools declarations, please see <a href=
     402  "annex_bld_cfg.html#tools-list">Annex: Declarations in FCM build
    450403  configuration file &gt; list of tools</a>.</p>
    451404
    452   <h3><a name="basic_interface">Automatic Fortran 9X interface block</a></h3>
     405  <h3 id="basic_interface">Automatic Fortran 9X interface block</h3>
    453406
    454407  <p>For each Fortran 9X source file containing standalone subroutines and/or
    455   functions, the system generates an interface file and sends it to the "inc/"
    456   sub-directory of the build root. An interface file contains the interface
    457   blocks for the subroutines and functions in the original source file. In an
    458   incremental build, if you have modified a Fortran 9X source file, its
    459   interface file will only be re-generated if the content of the interface has
    460   changed.</p>
    461  
    462   <p>Consider a source file "foo.f90" containing a subroutine called "foo". In a
    463   normal operation, the system writes the interface file to "foo.interface" in
    464   the "inc/" sub-directory of the build root. By default, the root name of the
    465   interface file is the same as that of the source file, and is case sensitive.
    466   You can change this behaviour using a "TOOL::INTERFACE" declaration. E.g.:</p>
    467 
     408  functions, the system generates an interface file and sends it to the
     409  <samp>inc/</samp> sub-directory of the build root. An interface file contains
     410  the interface blocks for the subroutines and functions in the original source
     411  file. In an incremental build, if you have modified a Fortran 9X source file,
     412  its interface file will only be re-generated if the content of the interface
     413  has changed.</p>
     414
     415  <p>Consider a source file <samp>foo.f90</samp> containing a subroutine called
     416  <samp>foo</samp>. In a normal operation, the system writes the interface file
     417  to <samp>foo.interface</samp> in the <samp>inc/</samp> sub-directory of the
     418  build root. By default, the root name of the interface file is the same as
     419  that of the source file, and is case sensitive. You can change this behaviour
     420  using a <code>TOOL::INTERFACE</code> declaration. E.g.:</p>
    468421  <pre>
    469422bld::tool::interface  program # The default is "file"
    … …  
    472425  <p>In such case, the root name of the interface file will be named in lower
    473426  case after the first program unit in the file.</p>
    474  
    475   <p>The default extension for an interface file is ".interface". This can be
    476   modified through the input and output file type register, which will be
    477   discussed in a later section on <a href="#advanced_file-type">File
     427
     428  <p>The default extension for an interface file is <samp>.interface</samp>.
     429  This can be modified through the input and output file type register, which
     430  will be discussed in a later section on <a href="#advanced_file-type">File
    478431  Type</a>.</p>
    479  
     432
    480433  <p>In most cases, we modify procedures without altering their calling
    481   interfaces. Consider another source file "bar.f90" containing a subroutine
    482   "bar". If "bar" calls "foo", it is good practice for "bar" to have an explicit
    483   interface for "foo". This can be achieved if the subroutine "bar" has the
    484   following within its declaration section:</p>
    485 
     434  interfaces. Consider another source file <samp>bar.f90</samp> containing a
     435  subroutine <samp>bar</samp>. If <samp>bar</samp> calls <samp>foo</samp>, it
     436  is good practice for <samp>bar</samp> to have an explicit interface for
     437  <samp>foo</samp>. This can be achieved if the subroutine <samp>bar</samp> has
     438  the following within its declaration section:</p>
    486439  <pre>
    487440INCLUDE 'foo.interface'
    488441</pre>
    489442
    490   <p>The source file "bar.f90" is now dependent on the interface file
    491   "foo.interface". This can make incremental build very efficient, as changes
    492   in the "foo.f90" file will not normally trigger the re-compilation of
    493   "bar.f90", provided that the interface of the subroutine "foo" remains
    494   unchanged. (However, the system is clever enough to know that it needs to
    495   re-link any executables that are dependent on the object file for the
    496   subroutine "bar".)</p>
    497 
    498   <p>The default interface block generator is a piece of "plugged-in" Perl
    499   code originally developed by the ECMWF. It has been modified at the Met
    500   Office to work with FCM. Currently, the system can also work with the
    501   interface generator <em>f90aib</em>, which is a freeware obtained from <a
    502   href="http://www.ifremer.fr/ditigo/molagnon/fortran90/contenu.html">Fortran
    503   90 texts and programs, assembled by Michel Olagnon</a> at the French
    504   Research Institute for Exploitation of the Sea. To do so, you need to make a
     443  <p>The source file <samp>bar.f90</samp> is now dependent on the interface
     444  file <samp>foo.interface</samp>. This can make incremental build very
     445  efficient, as changes in the <samp>foo.f90</samp> file will not normally
     446  trigger the re-compilation of <samp>bar.f90</samp>, provided that the
     447  interface of the <code>subroutine foo</code> remains unchanged. (However, the
     448  system is clever enough to know that it needs to re-link any executables that
     449  are dependent on the object file for the <code>subroutine bar</code>.)</p>
     450
     451  <p>By default, the system uses its own internal logic to extract the calling
     452  interfaces of top level subroutines and functions in a Fortran source file to
     453  generate an interface block. However, the system can also work with the
     454  interface generator <code>f90aib</code>, which is a freeware obtained from
     455  <a href=
     456  "http://www.ifremer.fr/ditigo/molagnon/fortran90/contenu.html">Fortran 90
     457  texts and programs, assembled by Michel Olagnon</a> at the French Research
     458  Institute for Exploitation of the Sea. To do so, you need to make a
    505459  declaration in the build configuration file using the label
    506   "TOOL::GENINTERFACE". As for any other TOOL declarations, you can attach a
    507   sub-package name to the label. The change will then apply only to source
    508   files within that sub-package. If "TOOL::GENINTERFACE" is declared to have
    509   the value "NONE", interface generation will be switched off. The following
     460  <code>TOOL::GENINTERFACE</code>. As for any other <code>TOOL</code>
     461  declarations, you can attach a sub-package name to the label. The change will
     462  then apply only to source files within that sub-package. If
     463  <code>TOOL::GENINTERFACE</code> is declared to have the value
     464  <code>NONE</code>, interface generation will be switched off. The following
    510465  are some examples:</p>
    511 
    512   <table class="pad" summary="build_example4" border="1" width="100%">
    513     <tr>
    514       <th>Build configuration example 4 - Fortran 9X interface block
    515       generator</th>
    516     </tr>
    517 
    518     <tr>
    519       <td>
    520         <pre>
     466  <pre id="example_4">
     467# Example 4
     468# ----------------------------------------------------------------------
    521469# This is an EXTRACT configuration file ...
    522470
    … …  
    524472
    525473bld::tool::geninterface       f90aib # line 5
    526 bld::tool::geninterface::foo  ECMWF  # line 6
    527 bld::tool::geninterface::bar  none   # line 7
     474bld::tool::geninterface::bar  none   # line 6
    528475
    529476# ... some other declarations ...
    530477</pre>
    531       </td>
    532     </tr>
    533   </table>
    534 
    535   <p>In line 5, the global interface generator is now set to <em>f90aib</em>.
    536   In line 6, the interface generator for the package "foo" is set to the ECMWF
    537   one. In line 7, by setting the interface generator for the package "bar" to
    538   the "none" keyword, no interface file will be generated for source files
    539   under the package "bar".</p>
     478
     479  <p>In line 5, the global interface generator is now set to
     480  <code>f90aib</code>. In line 6, by setting the interface generator for the
     481  package <samp>bar</samp> to the <code>none</code> keyword, no interface file
     482  will be generated for source files under the package <samp>bar</samp>.</p>
    540483
    541484  <p>Switching off the interface block generator can be useful in many
    … …  
    545488  the source file to speed up the build process.</p>
    546489
    547   <h3><a name="basic_dependency">Automatic dependency</a></h3>
     490  <h3 id="basic_dependency">Automatic dependency</h3>
    548491
    549492  <p>The build system has a built-in dependency scanner, which works out the
    … …  
    551494  the correct order. The system scans all source files of known types for all
    552495  supported dependency patterns. Dependencies of source files in a sub-package
    553   are written in a cache, which can be retrieved for incremental builds. (In
    554   an incremental build, only changed source files need to be re-scanned for
     496  are written in a cache, which can be retrieved for incremental builds. (In an
     497  incremental build, only changed source files need to be re-scanned for
    555498  dependency information. Dependency information for other files are retrieved
    556   from the cache.) The dependency information is parsed to the <em>make</em>
    557   rule generator, which writes the <em>Makefile</em> fragment for building the
    558   source files in the sub-package. In an incremental build, a
    559   <em>Makefile</em> fragment for a sub-package is only re-generated if a
    560   source file in the sub-package has changed.</p>
    561 
    562   <p>The <em>make</em> rule generator generates different <em>make</em> rules
    563   for different dependency types. The following dependency patterns are
     499  from the cache.) The dependency information is passed to the
     500  <code>make</code> rule generator, which writes the <samp>Makefile</samp>.</p>
     501
     502  <p>The <code>make</code> rule generator generates different <code>make</code>
     503  rules for different dependency types. The following dependency patterns are
    564504  automatically detected by the current system:</p>
    565505
    566506  <ul>
    567     <li>The [USE &lt;module&gt;] statement in a Fortran source file is the first
    568     pattern. The statement has two implications: 1) The current file compiles
    569     only if the module has been successfully compiled, and needs to be
    570     re-compiled if the module has changed. 2) The executable depending on the
    571     current file can only resolve all its externals by linking with the object
    572     file of the compiled module. The executable needs to be re-linked if the
    573     module and its dependencies has changed.</li>
    574 
    575     <li>The [INCLUDE '&lt;name&gt;.interface'] statement in a Fortran source
    576     file is the second pattern. (The default extension for an interface file is
    577     ".interface". This can be modified through the input and output file type
    578     register, which will be discussed in a later section on <a href=
    579     "#advanced_file-type">File Type</a>.) It has two implications: 1) The
    580     current file compiles only if the included interface file is in the INCLUDE
    581     search path, and needs to be re-compiled if the interface file changes. 2)
    582     The executable depending on the current file can only resolve all its
    583     externals by linking with the object file of the source file that generates
    584     the interface file. The executable needs to be re-linked if the source file
    585     (and its dependencies) associated with the interface file has changed. It is
    586     worth noting that for this dependency to work, the root &lt;name&gt; of the
    587     interface file should match with that of the source file associated with the
    588     interface file. (Please note that you can use pre-processor [#include
    589     "&lt;name&gt;.interface] instead of Fortran INCLUDE, but it will not work
    590     if you switch on the <a href="#advanced_pp">pre-processing</a> stage, which
    591     will be discussed in a later section.)</li>
    592 
    593     <li>The [INCLUDE '&lt;file&gt;'] statement (excluding the INCLUDE
    594     interface file statement) in a Fortran source file is the third pattern.
    595     It has two implications: 1) The current file compiles only if the included
     507    <li>The <code>USE &lt;module&gt;</code> statement in a Fortran source file
     508    is the first pattern. The statement has two implications: 1) The current
     509    file compiles only if the module has been successfully compiled, and needs
     510    to be re-compiled if the module has changed. 2) The executable depending on
     511    the current file can only resolve all its externals by linking with the
     512    object file of the compiled module. The executable needs to be re-linked if
     513    the module and its dependencies has changed.</li>
     514
     515    <li>The <code>INCLUDE '&lt;name&gt;.interface'</code> statement in a
     516    Fortran source file is the second pattern. (The default extension for an
     517    interface file is <samp>.interface</samp>. This can be modified through the
     518    input and output file type register, which will be discussed in a later
     519    section on <a href="#advanced_file-type">File Type</a>.) It has two
     520    implications: 1) The current file compiles only if the included interface
    596521    file is in the INCLUDE search path, and needs to be re-compiled if the
    597     include file changes. 2) The executable needs to be linked with any
    598     objects the include file is dependent on. It needs to be re-linked if
    599     these objects have changed.</li>
    600 
    601     <li>The [#include '&lt;file&gt;'] statement in a Fortran/C source or header
    602     file is the fourth pattern. It has similar implications as the Fortran
    603     INCLUDE statement. However, they have to be handled differently because
    604     "#include" statements are processed by the pre-processor, which may be
    605     performed in a separate stage of the FCM build process. This will be
    606     further discussed in a later sub-section on <a
    607     href="#advanced_pp">Pre-processing</a>.</li>
     522    interface file changes. 2) The executable depending on the current file can
     523    only resolve all its externals by linking with the object file of the
     524    source file that generates the interface file. The executable needs to be
     525    re-linked if the source file (and its dependencies) associated with the
     526    interface file has changed. It is worth noting that for this dependency to
     527    work, the root &lt;name&gt; of the interface file should match with that of
     528    the source file associated with the interface file. (Please note that you
     529    can use pre-processor [#include "&lt;name&gt;.interface] instead of Fortran
     530    INCLUDE, but it will not work if you switch on the <a href=
     531    "#advanced_pp">pre-processing</a> stage, which will be discussed in a later
     532    section.)</li>
     533
     534    <li>The <code>INCLUDE '&lt;file&gt;'</code> statement (excluding the
     535    INCLUDE interface file statement) in a Fortran source file is the third
     536    pattern. It has two implications: 1) The current file compiles only if the
     537    included file is in the INCLUDE search path, and needs to be re-compiled if
     538    the include file changes. 2) The executable needs to be linked with any
     539    objects the include file is dependent on. It needs to be re-linked if these
     540    objects have changed.</li>
     541
     542    <li>The <code>#include '&lt;file&gt;'</code> statement in a Fortran/C
     543    source or header file is the fourth pattern. It has similar implications as
     544    the Fortran INCLUDE statement. However, they have to be handled differently
     545    because <code>#include</code> statements are processed by the
     546    pre-processor, which may be performed in a separate stage of the FCM build
     547    process. This will be further discussed in a later sub-section on <a href=
     548    "#advanced_pp">Pre-processing</a>.</li>
    608549  </ul>
    609550
    … …  
    618559
    619560    <li>Always supply an interface for subroutines and functions, i.e.:
     561
    620562      <ul>
    621563        <li>Put them in modules.</li>
    … …  
    627569    </li>
    628570
    629     <li>If interface files are used, it is good practise to name each source
     571    <li>If interface files are used, it is good practice to name each source
    630572    file after the program unit it contains. It will make life a lot simpler
    631573    when using the <a href="#basic_interface">Automatic Fortran 9X interface
    632574    block</a> feature, which has already been discussed in the previous
    633575    section.
     576
    634577      <ul>
    635         <li>The problem is that, by default, the root name of the interface file
    636             is the same as that of the source file rather than the program unit.
    637             If they differ then the build system will create a dependency on the
    638             wrong object file (since the object files are named according to the
    639             program unit).</li>
    640         <li>This problem can be avoided by changing the behaviour of the interface
    641             file generator to use the name of the program unit instead (using a
    642             "TOOL::INTERFACE" declaration).</li>
     578        <li>The problem is that, by default, the root name of the interface
     579        file is the same as that of the source file rather than the program
     580        unit. If they differ then the build system will create a dependency on
     581        the wrong object file (since the object files are named according to
     582        the program unit).</li>
     583
     584        <li>This problem can be avoided by changing the behaviour of the
     585        interface file generator to use the name of the program unit instead
     586        (using a <code>TOOL::INTERFACE</code> declaration).</li>
    643587      </ul>
    644588    </li>
    645589  </ol>
    646590
    647   <table class="pad" summary=
    648   "note - setting build targets" border="1" width="100%">
    649     <tr>
    650       <th>Note - setting build targets</th>
    651     </tr>
    652 
    653     <tr>
    654       <td>
    655         The <em>Makefile</em> (and its include fragments) generated by the
    656         build system contains a list of targets that can be built. The build
    657         system allows you to build (or perform the actions of) any targets that
    658         are present in the generated <em>Makefile</em>. There are two ways to
    659         specify the targets to be built. Firstly, you can use the TARGET
    660         declarations in your build configuration file to specify the default
    661         targets to be built.  These targets will be set as dependencies of the
    662         "all" target in the generated <em>Makefile</em>, which is the default
    663         target to be built when <em>make</em> is invoked by FCM. Alternatively,
    664         you can use the "-t" option when you invoke the "fcm build" command. The
    665         option takes an argument, which should be a colon ":" separated list of
    666         targets to be built. When the "-t" option is set, FCM invokes
    667         <em>make</em> to build these targets instead. (E.g. if we invoke the
    668         build system with the command "fcm build -t foo.exe:bar.exe", it will
    669         invoke <em>make</em> to build "foo.exe" and "bar.exe".)
    670 
    671         <p>If you do not specify any explicit targets, the system will search
    672         your source tree for main programs:</p>
    673        
    674         <ul>
    675           <li>If there are main programs in your source tree, they will be set
    676           as the default targets automatically.</li>
    677 
    678           <li>Otherwise, the default is to build the top level library archive
    679           containing objects compiled from the source files in the current
    680           source tree. (For more information on building library archives,
    681           please see the section on <a href="#advanced_library">Creating
    682           library archives</a>.)</li>
    683         </ul>
    684       </td>
    685     </tr>
    686   </table>
    687 
    688   <h2><a name="advanced">Advanced Features</a></h2>
    689 
    690   <h3><a name="advanced_dependency">Further dependency features</a></h3>
     591  <dl>
     592    <dt>Note - setting build targets</dt>
     593
     594    <dd>
     595      <p>The <samp>Makefile</samp> generated by the build system contains a
     596      list of targets that can be built. The build system allows you to build
     597      (or perform the actions of) any targets that are present in the generated
     598      <samp>Makefile</samp>. There are two ways to specify the targets to be
     599      built.</p>
     600
     601      <p>Firstly, you can use the <code>TARGET</code> declarations in your
     602      build configuration file to specify the default targets to be built.
     603      These targets will be set as dependencies of the <samp>all</samp> target
     604      in the generated <samp>Makefile</samp>, which is the default target to be
     605      built when <code>make</code> is invoked by FCM. It is worth noting that
     606      <code>TARGET</code> declarations are cumulative. A later declaration does
     607      not override an earlier one - it simply adds more targets to the
     608      list.</p>
     609
     610      <p>Alternatively, you can use the <code>-t</code> option when you invoke
     611      the <code>fcm build</code> command. The option takes an argument, which
     612      should be a colon <code>:</code> separated list of targets to be built.
     613      When the <code>-t</code> option is set, FCM invokes <code>make</code> to
     614      build these targets instead. (E.g. if we invoke the build system with the
     615      command <code>fcm build -t foo.exe:bar.exe</code>, it will invoke
     616      <code>make</code> to build <samp>foo.exe</samp> and
     617      <samp>bar.exe</samp>.)</p>
     618
     619      <p>If you do not specify any explicit targets, the system will search
     620      your source tree for main programs:</p>
     621
     622      <ul>
     623        <li>If there are main programs in your source tree, they will be set as
     624        the default targets automatically.</li>
     625
     626        <li>Otherwise, the default is to build the top level library archive
     627        containing objects compiled from the source files in the current source
     628        tree. (For more information on building library archives, please see
     629        the section on <a href="#advanced_library">Creating library
     630        archives</a>.)</li>
     631      </ul>
     632    </dd>
     633  </dl>
     634
     635  <h2 id="advanced">Advanced Features</h2>
     636
     637  <h3 id="advanced_dependency">Further dependency features</h3>
    691638
    692639  <p>Apart from the usual dependency patterns described in the previous
    … …  
    695642
    696643  <ul>
    697     <li>The directive [DEPENDS ON: &lt;object&gt;] in a comment line of a
    698     Fortran/C source file: It states that the current file is dependent on the
    699     declared external object. The executable depending on the current file
     644    <li>The directive <code>DEPENDS ON: &lt;object&gt;</code> in a comment line
     645    of a Fortran/C source file: It states that the current file is dependent on
     646    the declared external object. The executable depending on the current file
    700647    needs to link with this external object in order to resolve all its
    701648    external references. It needs to be re-linked if the declared external
    702649    object (and its dependencies) has changed.</li>
    703650
    704     <li>The directive [CALLS: &lt;executable&gt;] in a comment line of a
    705     script: It states that the current script is dependent on the declared
     651    <li>The directive <code>CALLS: &lt;executable&gt;</code> in a comment line
     652    of a script: It states that the current script is dependent on the declared
    706653    executable file, which can be another script or a binary executable. The
    707654    current script can only function correctly if the declared executable is
    … …  
    710657  </ul>
    711658
    712   <p>There are situations when you need to bypass the automatic dependency
    713   scanner. In such case, you may need to use a package configuration file. For
    714   further information, please refer to the sub-section on <a href=
    715   "#advanced_pckcfg">Using a package configuration file</a>.</p>
    716 
    717   <p>Another way to specify external dependency is to use the EXE_DEP
    718   declaration to declare extra dependencies. The declaration normally applies to
    719   all main programs, but if the the form EXE_DEP::&lt;target&gt; is used, it
    720   will only apply to &lt;target&gt;, (which must be the name of a main program
    721   target). If the declaration is made without a value, the main programs will be
    722   set to depend on all object files. Otherwise, the value can be supplied as a
    723   space delimited list of items. Each item can be either the name of a
    724   sub-package or an object target. For the former, the main programs will be set
    725   to depend on all object files within the sub-package. For the latter, the main
    726   programs will be set to depend on the object target. The following are some
     659  <p>Another way to specify external dependency is to use the
     660  <code>EXE_DEP</code> declaration to declare extra dependencies. The
     661  declaration normally applies to all main programs, but if the form
     662  <code>EXE_DEP::&lt;target&gt;</code> is used, it will only apply to
     663  &lt;target&gt;, (which must be the name of a main program target). If the
     664  declaration is made without a value, the main programs will be set to depend
     665  on all object files. Otherwise, the value can be supplied as a space
     666  delimited list of items. Each item can be either the name of a sub-package or
     667  an object target. For the former, the main programs will be set to depend on
     668  all object files within the sub-package. For the latter, the main programs
     669  will be set to depend on the object target. The following are some
    727670  examples:</p>
    728 
    729   <table class="pad" summary="build_example5" border="1" width="100%">
    730     <tr>
    731       <th>Build configuration example 5 - extra executable dependency</th>
    732     </tr>
    733 
    734     <tr>
    735       <td>
    736         <pre>
     671  <pre id="example_5">
     672# Example 5
     673# ----------------------------------------------------------------------
    737674cfg::type          ext
    738675cfg::version       1.0
    739676
    740 bld::exe_dep::foo.exe  foo::bar egg.o # line 4
    741 bld::exe_dep                          # line 5
     677bld::exe_dep::foo.exe  foo/bar egg.o # line 4
     678bld::exe_dep                         # line 5
    742679# ... some other declarations ...
    743680</pre>
    744       </td>
    745     </tr>
    746   </table>
    747681
    748682  <p>Here is an explanation of what each line does:</p>
    749683
    750684  <ul>
    751     <li>line 4: this line declares the dependency on the sub-package "foo::bar"
    752     and the object target "egg.o" for building the main program target
    753     "foo.exe". The target "foo.exe" will now depends on all object files in the
    754     "foo::bar" sub-package as well as the object target "egg.o".</li>
    755 
    756     <li>line 5: this line declares that all other main program targets will
    757     depend on all (non-program) object files in the build.</li>
     685    <li><dfn>line 4</dfn>: this line declares the dependency on the sub-package
     686    <samp>foo/bar</samp> and the object target <samp>egg.o</samp> for building
     687    the main program target <samp>foo.exe</samp>. The target
     688    <samp>foo.exe</samp> will now depends on all object files in the
     689    <samp>foo/bar</samp> sub-package as well as the object target
     690    <samp>egg.o</samp>.</li>
     691
     692    <li><dfn>line 5</dfn>: this line declares that all other main program
     693    targets will depend on all (non-program) object files in the build.</li>
    758694  </ul>
    759695
    760   <table class="pad" summary="note - naming of object files" border="1"
    761   width="100%">
    762     <tr>
    763       <th>Note - naming of object files</th>
    764     </tr>
    765 
    766     <tr>
    767       <td>By default, object files are named with the suffix ".o". For a
    768       Fortran source file, the build system uses the lower case name of the
    769       first program unit within the file to name its object file. For example,
    770       if the first program unit in the Fortran source file "foo.f90" is
    771       "PROGRAM Bar", the object file will be "bar.o". For a C source file, the
    772       build system uses the lower case root name of the source file to name
    773       its object file. For example, a C source file called "egg.c" will have
    774       its object file named "egg.o".
    775      
    776         <p>The reason for using lower case to name the object files is because
    777         Fortran is a case insensitive language. Its symbols can either be in
    778         lower or upper case. E.g. the SUBROUTINE "Foo" is the same as the
    779         SUBROUTINE "foo". It can be rather confusing if the subroutines are
    780         stored in different files. When they are compiled and archived into a
    781         library, there will be a clash of namespace, as the Fortran compiler
    782         thinks they are the same. However, this type of error does not normally
    783         get reported. If "Foo" and "foo" are very different code, the user may
    784         end up using the wrong subroutine, which may lead to a very long
    785         debugging session. By naming all object files in lower case, this type
    786         of situation can be avoided. If there is a clash in names due to the use
    787         of upper/lower cases, it will be reported as warnings by <em>make</em>,
    788         (as "duplicated targets" for building "foo.o").</p>
    789       </td>
    790     </tr>
    791   </table>
    792  
     696  <dl>
     697    <dt>Note - naming of object files</dt>
     698
     699    <dd>
     700      <p>By default, object files are named with the suffix <samp>.o</samp>.
     701      For a Fortran source file, the build system uses the lower case name of
     702      the first program unit within the file to name its object file. For
     703      example, if the first program unit in the Fortran source file
     704      <samp>foo.f90</samp> is <code>PROGRAM Bar</code>, the object file will be
     705      <samp>bar.o</samp>. For a C source file, the build system uses the lower
     706      case root name of the source file to name its object file. For example, a
     707      C source file called <samp>egg.c</samp> will have its object file named
     708      <samp>egg.o</samp>.</p>
     709
     710      <p>The reason for using lower case to name the object files is because
     711      Fortran is a case insensitive language. Its symbols can either be in
     712      lower or upper case. E.g. the <code>SUBROUTINE Foo</code> is the same as
     713      the <code>SUBROUTINE foo</code>. It can be rather confusing if the
     714      subroutines are stored in different files. When they are compiled and
     715      archived into a library, there will be a clash of namespace, as the
     716      Fortran compiler thinks they are the same. However, this type of error
     717      does not normally get reported. If <samp>Foo</samp> and <samp>foo</samp>
     718      are very different code, the user may end up using the wrong subroutine,
     719      which may lead to a very long debugging session. By naming all object
     720      files in lower case, this type of situation can be avoided. If there is a
     721      clash in names due to the use of upper/lower cases, it will be reported
     722      as warnings by the build system, (as <em>duplicated targets</em> for
     723      building <samp>foo.o</samp>).</p>
     724    </dd>
     725  </dl>
     726
    793727  <p>It is realised that there are situations when an automatically detected
    794   dependency should not be written into the <em>Makefile</em>. For example,
    795   the dependency may be a standard module provided by the Fortran compiler,
    796   and does not need to be built in the usual way. In such case, we need to
    797   have a way to exclude this module during an automatic dependency scan.</p>
    798 
    799   <p>The EXCL_DEP declaration can be used to do just that. The following
    800   extract configuration contains some examples of the basic usage of the
    801   EXCL_DEP declaration:</p>
    802 
    803   <table class="pad" summary="build_example6" border="1" width="100%">
    804     <tr>
    805       <th>Build configuration example 6 - exclude dependency</th>
    806     </tr>
    807 
    808     <tr>
    809       <td>
    810         <pre>
     728  dependency should not be written into the <samp>Makefile</samp>. For example,
     729  the dependency may be a standard module provided by the Fortran compiler, and
     730  does not need to be built in the usual way. In such case, we need to have a
     731  way to exclude this module during an automatic dependency scan.</p>
     732
     733  <p>The <code>EXCL_DEP</code> declaration can be used to do just that. The
     734  following extract configuration contains some examples of the basic usage of
     735  the <code>EXCL_DEP</code> declaration:</p>
     736  <pre id="example_6">
     737# Example 6
     738# ----------------------------------------------------------------------
    811739cfg::type          ext
    812740cfg::version       1.0
    … …  
    820748# ... some other declarations ...
    821749</pre>
    822       </td>
    823     </tr>
    824   </table>
    825750
    826751  <p>Here is an explanation of what each line does:</p>
    827752
    828753  <ul>
    829     <li>line 4: this line declares that the Fortran module "YourFortranMod"
    830     should be excluded. The value of each EXCL_DEP declaration has two parts.
    831     The first part is a label that is used to define the type of dependency to
    832     be excluded. For a full list of these labels, please see the <a
    833     href="annex_bld_cfg.html#dependency-types">dependency types table</a> in
    834     the <a href="annex_bld_cfg.html">Annex:
    835     Declarations in FCM build configuration file</a>. The label "USE"
    836     denotes a Fortran module. The second part of the label is the dependency
    837     itself. For instance, if a Fortran source file contains the line: "USE
    838     YourFortranMod", the dependency scanner will ignore it.</li>
    839 
    840     <li>line 5: this line declares that the include statement for the Fortran
    841     9X interface file "HerFortran.interface" should be excluded. The label
    842     "INTERFACE" denotes a Fortran INCLUDE statement for a Fortran 9X interface
    843     block file. For example, if a Fortran source file contains the line:
    844     "INCLUDE 'HerFortran.interface'", the dependency scanner will
    845     ignore it.</li>
    846 
    847     <li>line 6: this line declares that the include statement for
    848     "HisFortranInc.inc" should be excluded. The label "INC" denotes a Fortran
    849     INCLUDE statement other than an INCLUDE statement for an interface block
    850     file. For example, if a Fortran source file contains the line:
    851     "INCLUDE 'HisFortranInc.inc'", the dependency scanner will ignore
    852     it.</li>
    853 
    854     <li>line 7: this line declares that the header include statement
    855     "TheirHeader.h" should be excluded. The label "H" denotes a pre-processing
    856     #include statement. For example, if a source file contains the line:
    857     "#include 'TheirHeader.h'", the dependency scanner will ignore
    858     it.</li>
    859 
    860     <li>line 8: this line declares that the external dependency for
    861     "ItsObject.o" should be excluded. The label "OBJ" denotes a compiled
    862     binary object. These dependencies are normally inserted into the source
    863     files as special comments. For example, if a source file contains the line:
    864     "! depends on: ItsObject.o", the dependency scanner will ignore
    865     it.</li>
     754    <li><dfn>line 4</dfn>: this line declares that the Fortran module
     755    <samp>YourFortranMod</samp> should be excluded. The value of each
     756    <code>EXCL_DEP</code> declaration has two parts. The first part is a label
     757    that is used to define the type of dependency to be excluded. For a full
     758    list of these labels, please see the <a href=
     759    "annex_bld_cfg.html#dependency-types">dependency types table</a> in the
     760    <a href="annex_bld_cfg.html">Annex: Declarations in FCM build configuration
     761    file</a>. The label <code>USE</code> denotes a Fortran module. The second
     762    part of the label is the dependency itself. For instance, if a Fortran
     763    source file contains the line: <code>USE YourFortranMod</code>, the
     764    dependency scanner will ignore it.</li>
     765
     766    <li><dfn>line 5</dfn>: this line declares that the include statement for
     767    the Fortran 9X interface file <samp>HerFortran.interface</samp> should be
     768    excluded. The label <code>INTERFACE</code> denotes a Fortran INCLUDE
     769    statement for a Fortran 9X interface block file. For example, if a Fortran
     770    source file contains the line: <code>INCLUDE 'HerFortran.interface'</code>,
     771    the dependency scanner will ignore it.</li>
     772
     773    <li><dfn>line 6</dfn>: this line declares that the include statement for
     774    <samp>HisFortranInc.inc</samp> should be excluded. The label
     775    <code>INC</code> denotes a Fortran INCLUDE statement other than an INCLUDE
     776    statement for an interface block file. For example, if a Fortran source
     777    file contains the line: <code>INCLUDE 'HisFortranInc.inc'</code>, the
     778    dependency scanner will ignore it.</li>
     779
     780    <li><dfn>line 7</dfn>: this line declares that the header include statement
     781    <samp>TheirHeader.h</samp> should be excluded. The label <code>H</code>
     782    denotes a pre-processing #include statement. For example, if a source file
     783    contains the line: <code>#include 'TheirHeader.h'</code>, the dependency
     784    scanner will ignore it.</li>
     785
     786    <li><dfn>line 8</dfn>: this line declares that the external dependency for
     787    <samp>ItsObject.o</samp> should be excluded. The label <code>OBJ</code>
     788    denotes a compiled binary object. These dependencies are normally inserted
     789    into the source files as special comments. For example, if a source file
     790    contains the line: <code>! depends on: ItsObject.o</code>, the dependency
     791    scanner will ignore it.</li>
    866792  </ul>
    867793
    868   <p>An EXCL_DEP declaration normally applies to all files in the build.
    869   However, you can suffix it with the name of a sub-package, i.e.
    870   EXCL_DEP::&lt;pcks&gt;. In such case, the declaration will only apply while
    871   scanning for dependencies in the source files in the sub-package named
    872   &lt;pcks&gt;.</p>
     794  <p>An <code>EXCL_DEP</code> declaration normally applies to all files in the
     795  build. However, you can suffix it with the name of a sub-package, i.e.
     796  <code>EXCL_DEP::&lt;pcks&gt;</code>. In such case, the declaration will only
     797  apply while scanning for dependencies in the source files in the sub-package
     798  named &lt;pcks&gt;.</p>
    873799
    874800  <p>You can also exclude all dependency scan of a particular type. To do so,
    875801  simply declare the type in the value. For example, if you do not want the
    876   build system to scan for the [CALLS: &lt;executable&gt;] directive in the
    877   comment lines of your scripts, you can make the following declaration:</p>
    878 
     802  build system to scan for the <code>CALLS: &lt;executable&gt;</code> directive
     803  in the comment lines of your scripts, you can make the following
     804  declaration:</p>
    879805  <pre>
    880806bld::excl_dep  EXE
    881807</pre>
    882808
    883   <p>N.B. Currently, the build system is unable to detect changes in EXCL_DEP
    884   declarations. Therefore, you will need to invoke the build system in full
    885   build mode if you have changed these settings.</p>
    886 
    887   <h3><a name="advanced_blockdata">Linking a Fortran executable with a BLOCKDATA
    888   program unit</a></h3>
    889 
    890   <p>If it is required to link Fortran executables with BLOCKDATA program units,
    891   you must declare the executable targets and the objects containing the
    892   BLOCKDATA program units using the BLOCKDATA::&lt;target&gt; declarations. For
    893   example, if "foo.exe" is an executable target depending on the objects of the
    894   BLOCKDATA program units "blkdata.o" and "fbk.o", you will make the following
     809  <p>The opposite of the <code>EXCL_DEP</code> declaration is the
     810  <code>DEP::&lt;pcks&gt;</code> declaration, which you can use to add a
     811  dependency to a source file (in the package name <code>&lt;pcks&gt;</code>).
     812  The syntax of the declaration is similar to that of <code>EXCL_DEP</code>,
     813  but you must specify the package name of a source file for DEP declarations.
     814  Please also note that a <code>DEP</code> declaration only works if the
     815  particular dependency is supported for the particular source file - as it
     816  makes no sense, for example, to specify a USE dependency for a shell
     817  script.</p>
     818
     819  <p>If you need to switch off dependency checking completely, you can use the
     820  <code>NO_DEP</code> declaration. For example, to switch off dependency
     821  checking for all but the <samp>foo/bar</samp> sub-package, you can do:</p>
     822  <pre>
     823bld::no_dep           true
     824bld::no_dep::foo/bar  false
     825</pre>
     826
     827  <h3 id="advanced_blockdata">Linking a Fortran executable with a BLOCKDATA
     828  program unit</h3>
     829
     830  <p>If it is required to link Fortran executables with BLOCKDATA program
     831  units, you must declare the executable targets and the objects containing the
     832  BLOCKDATA program units using the <code>BLOCKDATA::&lt;target&gt;</code>
     833  declarations. For example, if <samp>foo.exe</samp> is an executable target
     834  depending on the objects of the BLOCKDATA program units
     835  <samp>blkdata.o</samp> and <samp>fbk.o</samp>, you will make the following
    895836  declarations:</p>
    896 
    897837  <pre>
    898838bld::blockdata::foo.exe  blkdata fbk
    899839</pre>
    900840
    901   <p>If all your executables are dependent on "blkdata.o" and "fbk.o", you will
    902   make the following declarations:</p>
    903 
     841  <p>If all your executables are dependent on <samp>blkdata.o</samp> and
     842  <samp>fbk.o</samp>, you will make the following declarations:</p>
    904843  <pre>
    905844bld::blockdata  blkdata fbk
    906845</pre>
    907846
    908   <h3><a name="advanced_library">Creating library archives</a></h3>
    909 
    910   <p>If you are interested in building library archives, the build system allows
    911   you to do it in a relatively simple way. For each sub-package in the source
    912   tree, there is a target to build a library containing all the objects compiled
    913   from the source files (that are not main programs) within the sub-package. If
    914   the sub-package contains children sub-packages, the object files of the
    915   children will also be included recursively. By default, the library archive is
    916   named after the sub-package, in the format "lib&lt;pcks&gt;.a". (For example,
    917   the library archive for the package "foo::bar::egg" will be named
    918   "libfoo__bar__egg.a" by default.) If you do not like the default name for the
    919   sub-package library, you can use the LIB::&lt;pcks&gt; declaration to rename
    920   it, as long as the new name does not clash with other targets. For example, to
    921   rename "libfoo__bar__egg.a" to "libham.a", you will make the following
    922   declaration in your extract configuration file:</p>
    923 
     847  <h3 id="advanced_library">Creating library archives</h3>
     848
     849  <p>If you are interested in building library archives, the build system
     850  allows you to do it in a relatively simple way. For each sub-package in the
     851  source tree, there is a target to build a library containing all the objects
     852  compiled from the source files (that are not main programs) within the
     853  sub-package. If the sub-package contains children sub-packages, the object
     854  files of the children will also be included recursively. By default, the
     855  library archive is named after the sub-package, in the format
     856  <code>lib&lt;pcks&gt;.a</code>. (For example, the library archive for the
     857  package <samp>foo/bar/egg</samp> will be named
     858  <samp>libfoo__bar__egg.a</samp> by default.) If you do not like the default
     859  name for the sub-package library, you can use the
     860  <code>LIB::&lt;pcks&gt;</code> declaration to rename it, as long as the new
     861  name does not clash with other targets. For example, to rename
     862  <samp>libfoo__bar__egg.a</samp> to <samp>libham.a</samp>, you will make the
     863  following declaration in your extract configuration file:</p>
    924864  <pre>
    925 bld::lib::foo::bar::egg  ham
     865bld::lib::foo/bar/egg  ham
    926866</pre>
    927867
    928868  <p>In addition to sub-package libraries, you can also build a global library
    929869  archive for the whole source tree. By default, the library is named
    930   "libfcm_default.a", but you can rename it using the LIB declaration as above.
    931   For example, to rename the library to "libmy-lib.a", you will make the
    932   following declaration in your extract configuration file:</p>
    933 
     870  <samp>libfcm_default.a</samp>, but you can rename it using the
     871  <code>LIB</code> declaration as above. For example, to rename the library to
     872  <samp>libmy-lib.a</samp>, you will make the following declaration in your
     873  extract configuration file:</p>
    934874  <pre>
    935875bld::lib  my-lib
    … …  
    938878  <p>When a library archive is created successfully, the build system will
    939879  automatically generate the relevant exclude dependency configurations in the
    940   "etc/" sub-directory of the build root. You will be able to include these
    941   configurations in subsequent builds that utilise the library. The root names
    942   of the configuration files match those of the library archives that you can
    943   create in the current build, but the extension "*.a" is replaced with "*.cfg".
    944   For example, the exclude dependency configuration for "libmy-lib.a"
    945   is "libmy-lib.cfg".</p>
    946 
    947   <h3><a name="advanced_pp">Pre-processing</a></h3>
     880  <samp>etc/</samp> sub-directory of the build root. You will be able to
     881  include these configurations in subsequent builds that utilise the library.
     882  The root names of the configuration files match those of the library archives
     883  that you can create in the current build, but the extension <samp>*.a</samp>
     884  is replaced with <samp>*.cfg</samp>. For example, the exclude dependency
     885  configuration for <samp>libmy-lib.a</samp> is <samp>libmy-lib.cfg</samp>.</p>
     886
     887  <h3 id="advanced_pp">Pre-processing</h3>
    948888
    949889  <p>As most modern compilers can handle pre-processing, the build system
    … …  
    952892  argument list of procedures and/or their dependencies. If a source file
    953893  requires pre-processing in such a way, we have to pre-process before running
    954   the interface block generator and the dependency scanner. The PP declaration
    955   can be used to switch on this pre-processing stage. The pre-processing stage
    956   can be switched on globally or for individual sub-packages only. The
    957   following is an example, using an extract configuration file:</p>
    958 
    959   <table class="pad" summary="build_example7" border="1" width="100%">
    960     <tr>
    961       <th>Build configuration example 7 - pre-processing switch</th>
    962     </tr>
    963 
    964     <tr>
    965       <td>
    966         <pre>
     894  the interface block generator and the dependency scanner. The <code>PP</code>
     895  declaration can be used to switch on this pre-processing stage. The
     896  pre-processing stage can be switched on globally or for individual
     897  sub-packages only. The following is an example, using an extract
     898  configuration file:</p>
     899  <pre id="example_7">
     900# Example 7
     901# ----------------------------------------------------------------------
    967902cfg::type          ext
    968903cfg::version       1.0
    969904
    970 bld::pp::gen       1                     # line 4
    971 bld::pp::var::foo  1                     # line 5
     905bld::pp::gen       true                  # line 4
     906bld::pp::var/foo   true                  # line 5
    972907
    973908bld::tool::cppkeys GOOD WEATHER FORECAST # line 7
    … …  
    976911# ... some other declarations ...
    977912</pre>
    978       </td>
    979     </tr>
    980   </table>
    981913
    982914  <p>Here is an explanation of what each line does:</p>
    983915
    984916  <ul>
    985     <li>line 4 to 5: these switches on the pre-processing stage for all
    986     sub-packages under "gen" and "var::foo".</li>
    987 
    988     <li>line 7: this declares a list of pre-defined macros "GOOD", "WEATHER"
    989     and "FORECAST" for pre-processing all C files.</li>
    990 
    991     <li>line 8: this declares a list of pre-defined macros "FOO", "BAR",
    992     "EGG" and "HAM" for pre-processing all Fortran files that require
    993     processing.</li>
     917    <li><dfn>line 4-5</dfn>: these switches on the pre-processing stage for all
     918    sub-packages under <samp>gen</samp> and <samp>var/foo</samp>.</li>
     919
     920    <li><dfn>line 7</dfn>: this declares a list of pre-defined macros
     921    <samp>GOOD</samp>, <samp>WEATHER</samp> and <samp>FORECAST</samp> for
     922    pre-processing all C files.</li>
     923
     924    <li><dfn>line 8</dfn>: this declares a list of pre-defined macros
     925    <samp>FOO</samp>, <samp>BAR</samp>, <samp>EGG</samp> and <samp>HAM</samp>
     926    for pre-processing all Fortran files that require processing.</li>
    994927  </ul>
    995928
    996   <p>Source files requiring pre-processing may contain "#include" statements to
    997   include header files. For including a local file, its name should be embedded
    998   within a pair of quotes, i.e. 'file.h' or "file.h". If the header file is
    999   embedded within a pair of "&lt;file.h&gt;" angle brackets, the system will
    1000   assume that the file can be found in a standard location.</p>
     929  <p>Source files requiring pre-processing may contain <code>#include</code>
     930  statements to include header files. For including a local file, its name
     931  should be embedded within a pair of quotes, i.e. <samp>'file.h'</samp> or
     932  <samp>"file.h"</samp>. If the header file is embedded within a pair of
     933  &lt;file.h&gt; angle brackets, the system will assume that the file can be
     934  found in a standard location.</p>
    1001935
    1002936  <p>The build system allows header files to be placed anywhere within the
    1003   declared source tree. The system uses the dependency scanner, as described
    1004   in the previous sub-section to scan for any header file dependencies. All
    1005   source files requiring pre-processing and all header files are scanned. Header
    1006   files that are required are copied to the "inc/" subdirectory of the build
    1007   root, which is automatically added to the pre-processor search path via the
    1008   "-I&lt;dir&gt;" option. The build system uses an internal logic similar to
    1009   <em>make</em> to perform pre-processing. Header files are only copied to the
    1010   "inc/" sub-directory if they are used in "#include" statements.</p>
    1011  
    1012   <p>Unlike <em>make</em>, which only uses the timestamp to determine whether an
    1013   item is out of date, the internal logic of the build system does this by
    1014   inspecting the content of the file as well. In an incremental build, the
    1015   pre-processed file is only updated if its content has changed. This avoids
    1016   unnecessary updates (and hence unnecessary re-compilation) in an incremental
    1017   build if the changed section of the code does not affect the output file.</p>
     937  declared source tree. The system uses the dependency scanner, as described in
     938  the previous sub-section to scan for any header file dependencies. All source
     939  files requiring pre-processing and all header files are scanned. Header files
     940  that are required are copied to the <samp>inc/</samp> subdirectory of the
     941  build root, which is automatically added to the pre-processor search path via
     942  the <code>-I&lt;dir&gt;</code> option. The build system uses an internal
     943  logic similar to <code>make</code> to perform pre-processing. Header files
     944  are only copied to the <samp>inc/</samp> sub-directory if they are used in
     945  <code>#include</code> statements.</p>
     946
     947  <p>Unlike <code>make</code>, which only uses the timestamp to determine
     948  whether an item is out of date, the internal logic of the build system does
     949  this by inspecting the content of the file as well. In an incremental build,
     950  the pre-processed file is only updated if its content has changed. This
     951  avoids unnecessary updates (and hence unnecessary re-compilation) in an
     952  incremental build if the changed section of the code does not affect the
     953  output file.</p>
    1018954
    1019955  <p>Pre-processed code generated during the pre-processing stage are sent to
    1020   the "ppsrc/" sub-directory of the build root. It will have a relative path
    1021   that reflects the name of the declared sub-package. The pre-processed source
    1022   file will have the same root name as the original source file. For C files,
    1023   the same extension ".c" will be used. For Fortran files, the case of the
    1024   extension will normally be dropped, e.g. from ".F90" to ".f90".</p>
    1025  
     956  the <samp>ppsrc/</samp> sub-directory of the build root. It will have a
     957  relative path that reflects the name of the declared sub-package. The
     958  pre-processed source file will have the same root name as the original source
     959  file. For C files, the same extension <samp>.c</samp> will be used. For
     960  Fortran files, the case of the extension will normally be dropped, e.g. from
     961  <samp>.F90</samp> to <samp>.f90</samp>.</p>
     962
    1026963  <p>Following pre-processing, the system will use the pre-processed source
    1027964  file as if it is the original source file. The interface generator will
    … …  
    1030967  will compile the pre-processed source.</p>
    1031968
    1032   <p>The TOOL::CPPKEYS and TOOL::FPPKEYS declarations are used to pre-define
    1033   macros in the C and Fortran pre-processor respectively. This is implemented
    1034   by the build system using the pre-processor "-D" option on each word in the
    1035   list. The use of these declarations are not confined to the pre-process
    1036   stage. If any source files requiring pre-processing are left to the compiler,
    1037   the declarations will be used to set up the commands for compiling these
    1038   source files.</p>
    1039 
    1040   <p>The TOOL::CPPKEYS and TOOL::FPPKEYS declarations normally applies
    1041   globally, but like any other TOOL declarations, they can be suffixed with
    1042   sub-package names. In such cases, the declarations will apply only to the
    1043   specified sub-packages.</p>
    1044 
    1045   <table class="pad" summary="note - changing pre-processor flags" border="1"
    1046   width="100%">
    1047     <tr>
    1048       <th>Note - changing pre-processor flags</th>
    1049     </tr>
    1050 
    1051     <tr>
    1052       <td>
    1053         As for compiler flags, the build system detects changes in
    1054         pre-processor flags (TOOL::CPPFLAGS and TOOL::FPPFLAGS) and macro
    1055         definitions (TOOL::CPPKEYS and TOOL::FPPKEYS). If the pre-processor
    1056         flags or the macro definitions have changed in an incremental build,
    1057         the system will re-do all the necessary pre-processing. The following
    1058         hierarchy is followed:
    1059 
    1060         <ul>
    1061           <li>If the pre-processor flags or macro definitions for a particular
    1062           source file change, only that source file will be pre-processed
    1063           again.</li>
    1064 
    1065           <li>If the pre-processor flags or macro definitions for a particular
    1066           sub-package change, only source files within that sub-package will
    1067           be pre-processed again.</li>
    1068 
    1069           <li>If the global pre-processor flags or macro definitions change,
    1070           all source files will be pre-processed again.</li>
    1071 
    1072           <li>If the pre-processor command changes, all source files are
    1073           pre-processed again.</li>
    1074         </ul>
    1075       </td>
    1076     </tr>
    1077   </table>
    1078 
    1079   <h3><a name="advanced_file-type">File type</a></h3>
     969  <p>The <code>TOOL::CPPKEYS</code> and <code>TOOL::FPPKEYS</code> declarations
     970  are used to pre-define macros in the C and Fortran pre-processor
     971  respectively. This is implemented by the build system using the pre-processor
     972  <code>-D</code> option on each word in the list. The use of these
     973  declarations are not confined to the pre-process stage. If any source files
     974  requiring pre-processing are left to the compiler, the declarations will be
     975  used to set up the commands for compiling these source files.</p>
     976
     977  <p>The <code>TOOL::CPPKEYS</code> and <code>TOOL::FPPKEYS</code> declarations
     978  normally applies globally, but like any other <code>TOOL</code> declarations,
     979  they can be suffixed with sub-package names. In such cases, the declarations
     980  will apply only to the specified sub-packages.</p>
     981
     982  <dl>
     983    <dt>Note - changing pre-processor flags</dt>
     984
     985    <dd>
     986      <p>As for compiler flags, the build system detects changes in
     987      pre-processor flags (<code>TOOL::CPPFLAGS</code> and
     988      <code>TOOL::FPPFLAGS</code>) and macro definitions
     989      (<code>TOOL::CPPKEYS</code> and <code>TOOL::FPPKEYS</code>). If the
     990      pre-processor flags or the macro definitions have changed in an
     991      incremental build, the system will re-do all the necessary
     992      pre-processing. The following hierarchy is followed:</p>
     993
     994      <ul>
     995        <li>If the pre-processor flags or macro definitions for a particular
     996        source file change, only that source file will be pre-processed
     997        again.</li>
     998
     999        <li>If the pre-processor flags or macro definitions for a particular
     1000        container package change, only source files within that container will
     1001        be pre-processed again.</li>
     1002
     1003        <li>If the global pre-processor flags or macro definitions change, all
     1004        source files will be pre-processed again.</li>
     1005
     1006        <li>If the pre-processor command changes, all source files are
     1007        pre-processed again.</li>
     1008      </ul>
     1009    </dd>
     1010  </dl>
     1011
     1012  <h3 id="advanced_file-type">File type</h3>
    10801013
    10811014  <p>The build system only knows what to do with an input source file if it
    … …  
    10961029    <li>If the above two methods failed and if the file is a text file, the
    10971030    system will attempt to read the first line of the file. If the first line
    1098     begins with a "#!" pattern, the line will be compared with a set of
    1099     pre-defined patterns. If a match is found, the file type will be set
     1031    begins with a <code>#!</code> pattern, the line will be compared with a set
     1032    of pre-defined patterns. If a match is found, the file type will be set
    11001033    according to the file type associated with the pattern.</li>
    11011034  </ol>
    … …  
    11071040  source file.</p>
    11081041
    1109   <p>The build system registers a file type with a set of type flags
    1110   delimited by the double colons "::". For example, a Fortran 9X source file is
    1111   registered as "FORTRAN::FORTRAN9X::SOURCE". (Please note that the
    1112   order of the type flags in the list is insignificant. For example,
    1113   "FORTRAN::SOURCE" is the same as "SOURCE::FORTRAN".) For a list of all the
    1114   type flags used by the build system, please see the <a
    1115   href="annex_bld_cfg.html#infile-ext-types">input file extension type
    1116   flags table</a> in the <a href="annex_bld_cfg.html">
    1117   Annex: Declarations in FCM build configuration file</a>.</p>
    1118  
     1042  <p>The build system registers a file type with a set of type flags delimited
     1043  by the double colons <code>::</code>. For example, a Fortran 9X source file
     1044  is registered as <code>FORTRAN::FORTRAN9X::SOURCE</code>. (Please note that
     1045  the order of the type flags in the list is insignificant. For example,
     1046  <code>FORTRAN::SOURCE</code> is the same as <code>SOURCE::FORTRAN</code>.)
     1047  For a list of all the type flags used by the build system, please see the
     1048  <a href="annex_bld_cfg.html#infile-ext-types">input file extension type flags
     1049  table</a> in the <a href="annex_bld_cfg.html">Annex: Declarations in FCM
     1050  build configuration file</a>.</p>
     1051
    11191052  <p>The following is a list of default input file extensions and their
    11201053  associated types:</p>
    11211054
    1122   <table class="pad" summary="list of known file extensions" border="1">
    1123     <tr>
    1124       <th>Extensions</th>
    1125 
    1126       <th>Type flags</th>
    1127 
    1128       <th>Description</th>
    1129     </tr>
    1130 
    1131     <tr>
    1132       <td class="mono">.f .for .ftn .f77</td>
    1133 
    1134       <td class="mono">FORTRAN::SOURCE</td>
    1135 
    1136       <td>Fortran 77 source file (assumed to be fixed format)</td>
    1137     </tr>
    1138 
    1139     <tr>
    1140       <td class="mono">.f90 .f95</td>
    1141 
    1142       <td class="mono">FORTRAN::FORTRAN9X::SOURCE</td>
    1143 
    1144       <td>Fortran 9X source file (assumed to be free format)</td>
    1145     </tr>
    1146 
    1147     <tr>
    1148       <td class="mono">.F .FOR .FTN .F77</td>
    1149 
    1150       <td class="mono">FPP::SOURCE</td>
    1151 
    1152       <td>Fortran 77 source file (assumed to be fixed format) that requires
    1153       pre-processing</td>
    1154     </tr>
    1155 
    1156     <tr>
    1157       <td class="mono">.F90 .F95</td>
    1158 
    1159       <td class="mono">FPP::FPP9X::SOURCE</td>
    1160 
    1161       <td>Fortran 9X source file (assumed to be free format) that requires
    1162       pre-processing</td>
    1163     </tr>
    1164 
    1165     <tr>
    1166       <td class="mono">.c</td>
    1167 
    1168       <td class="mono">C::SOURCE</td>
    1169 
    1170       <td>C source file</td>
    1171     </tr>
    1172 
    1173     <tr>
    1174       <td class="mono">.h .h90</td>
    1175 
    1176       <td class="mono">CPP::INCLUDE</td>
    1177 
    1178       <td>Pre-processor "#include" header file</td>
    1179     </tr>
    1180 
    1181     <tr>
    1182       <td class="mono">.o .obj</td>
    1183 
    1184       <td class="mono">BINARY::OBJ</td>
    1185 
    1186       <td>Compiled binary object</td>
    1187     </tr>
    1188 
    1189     <tr>
    1190       <td class="mono">.exe</td>
    1191 
    1192       <td class="mono">BINARY::EXE</td>
    1193 
    1194       <td>Binary executable</td>
    1195     </tr>
    1196 
    1197     <tr>
    1198       <td class="mono">.a</td>
    1199 
    1200       <td class="mono">BINARY::LIB</td>
    1201 
    1202       <td>Binary object library archive</td>
    1203     </tr>
    1204 
    1205     <tr>
    1206       <td class="mono">.sh .ksh .bash .csh</td>
    1207 
    1208       <td class="mono">SHELL::SCRIPT</td>
    1209 
    1210       <td>Unix shell script</td>
    1211     </tr>
    1212 
    1213     <tr>
    1214       <td class="mono">.pl .pm</td>
    1215 
    1216       <td class="mono">PERL::SCRIPT</td>
    1217 
    1218       <td>Perl script</td>
    1219     </tr>
    1220 
    1221     <tr>
    1222       <td class="mono">.py</td>
    1223 
    1224       <td class="mono">PYTHON::SCRIPT</td>
    1225 
    1226       <td>Python script</td>
    1227     </tr>
    1228 
    1229     <tr>
    1230       <td class="mono">.tcl</td>
    1231 
    1232       <td class="mono">TCL::SCRIPT</td>
    1233 
    1234       <td>Tcl/Tk script</td>
    1235     </tr>
    1236 
    1237     <tr>
    1238       <td class="mono">.pro</td>
    1239 
    1240       <td class="mono">PVWAVE::SCRIPT</td>
    1241 
    1242       <td>PVWave program</td>
    1243     </tr>
    1244 
    1245     <tr>
    1246       <td class="mono">.cfg</td>
    1247 
    1248       <td class="mono">CFGFILE</td>
    1249 
    1250       <td>FCM configuration file</td>
    1251     </tr>
    1252 
    1253     <tr>
    1254       <td class="mono">.inc</td>
    1255 
    1256       <td class="mono">FORTRAN::FORTRAN9X::INCLUDE</td>
    1257 
    1258       <td>Fortran INCLUDE file</td>
    1259     </tr>
    1260 
    1261     <tr>
    1262       <td class="mono">.interface</td>
    1263 
    1264       <td class="mono">FORTRAN::FORTRAN9X::INCLUDE::INTERFACE</td>
    1265 
    1266       <td>Fortran 9X INCLUDE interface block file</td>
    1267     </tr>
    1268   </table>
     1055  <dl>
     1056    <dt><samp>.f .for .ftn .f77</samp></dt>
     1057
     1058    <dd><code>FORTRAN::SOURCE</code> Fortran 77 source file (assumed to be
     1059    fixed format)</dd>
     1060
     1061    <dt><samp>.f90 .f95</samp></dt>
     1062
     1063    <dd><code>FORTRAN::FORTRAN9X::SOURCE</code> Fortran 9X source file (assumed
     1064    to be free format)</dd>
     1065
     1066    <dt><samp>.F .FOR .FTN .F77</samp></dt>
     1067
     1068    <dd><code>FPP::SOURCE</code> Fortran 77 source file (assumed to be fixed
     1069    format) that requires pre-processing</dd>
     1070
     1071    <dt><samp>.F90 .F95</samp></dt>
     1072
     1073    <dd><code>FPP::FPP9X::SOURCE</code> Fortran 9X source file (assumed to be
     1074    free format) that requires pre-processing</dd>
     1075
     1076    <dt><samp>.c</samp></dt>
     1077
     1078    <dd><code>C::SOURCE</code> C source file</dd>
     1079
     1080    <dt><samp>.h .h90</samp></dt>
     1081
     1082    <dd><code>CPP::INCLUDE</code> Pre-processor <code>#include</code> header
     1083    file</dd>
     1084
     1085    <dt><samp>.o .obj</samp></dt>
     1086
     1087    <dd><code>BINARY::OBJ</code> Compiled binary object</dd>
     1088
     1089    <dt><samp>.exe</samp></dt>
     1090
     1091    <dd><code>BINARY::EXE</code> Binary executable</dd>
     1092
     1093    <dt><samp>.a</samp></dt>
     1094
     1095    <dd><code>BINARY::LIB</code> Binary object library archive</dd>
     1096
     1097    <dt><samp>.sh .ksh .bash .csh</samp></dt>
     1098
     1099    <dd><code>SHELL::SCRIPT</code> Unix shell script</dd>
     1100
     1101    <dt><samp>.pl .pm</samp></dt>
     1102
     1103    <dd><code>PERL::SCRIPT</code> Perl script</dd>
     1104
     1105    <dt><samp>.py</samp></dt>
     1106
     1107    <dd><code>PYTHON::SCRIPT</code> Python script</dd>
     1108
     1109    <dt><samp>.tcl</samp></dt>
     1110
     1111    <dd><code>TCL::SCRIPT</code> Tcl/Tk script</dd>
     1112
     1113    <dt><samp>.pro</samp></dt>
     1114
     1115    <dd><code>PVWAVE::SCRIPT</code> IDL/PVWave program</dd>
     1116
     1117    <dt><samp>.cfg</samp></dt>
     1118
     1119    <dd><code>CFGFILE</code> FCM configuration file</dd>
     1120
     1121    <dt><samp>.inc</samp></dt>
     1122
     1123    <dd><code>FORTRAN::FORTRAN9X::INCLUDE</code> Fortran INCLUDE file</dd>
     1124
     1125    <dt><samp>.interface</samp></dt>
     1126
     1127    <dd><code>FORTRAN::FORTRAN9X::INCLUDE::INTERFACE</code> Fortran 9X INCLUDE
     1128    interface block file</dd>
     1129  </dl>
    12691130
    12701131  <p>N.B. The extension must be unique. For example, the system does not
    1271   support the use of ".inc" files for both "#include" and Fortran
    1272   "INCLUDE".</p>
     1132  support the use of <samp>.inc</samp> files for both <code>#include</code> and
     1133  Fortran <code>INCLUDE</code>.</p>
    12731134
    12741135  <p>The following is a list of supported file name patterns and their
    12751136  associated types:</p>
    12761137
    1277   <table class="pad" summary="list of known file name patterns" border="1">
    1278     <tr>
    1279       <th>Patterns</th>
    1280 
    1281       <th>Type flags</th>
    1282 
    1283       <th>Description</th>
    1284     </tr>
    1285 
    1286     <tr>
    1287       <td class="mono">*Scr_* *Comp_* *IF_* *Suite_* *Interface_*</td>
    1288 
    1289       <td class="mono">SHELL::SCRIPT</td>
    1290 
    1291       <td>Unix shell script, GEN-based project naming conventions</td>
    1292     </tr>
    1293 
    1294     <tr>
    1295       <td class="mono">*List_*</td>
    1296 
    1297       <td class="mono">SHELL::SCRIPT::GENLIST</td>
    1298 
    1299       <td>Unix shell script, GEN "list" file</td>
    1300     </tr>
    1301 
    1302     <tr>
    1303       <td class="mono">*Sql_*</td>
    1304 
    1305       <td class="mono">SCRIPT::SQL</td>
    1306 
    1307       <td>SQL script, GEN-based project naming conventions</td>
    1308     </tr>
    1309   </table>
    1310 
    1311   <p>The following is a list of supported "#!" line patterns and their
    1312   associated types:</p>
    1313 
    1314   <table class="pad" summary="list of known file name patterns" border="1">
    1315     <tr>
    1316       <th>Patterns</th>
    1317 
    1318       <th>Type flags</th>
    1319 
    1320       <th>Description</th>
    1321     </tr>
    1322 
    1323     <tr>
    1324       <td class="mono">*sh* *ksh* *bash* *csh*</td>
    1325 
    1326       <td class="mono">SHELL::SCRIPT</td>
    1327 
    1328       <td>Unix shell script</td>
    1329     </tr>
    1330 
    1331     <tr>
    1332       <td class="mono">*perl*</td>
    1333 
    1334       <td class="mono">PERL::SCRIPT</td>
    1335 
    1336       <td>Perl script</td>
    1337     </tr>
    1338 
    1339     <tr>
    1340       <td class="mono">*python*</td>
    1341 
    1342       <td class="mono">PYTHON::SCRIPT</td>
    1343 
    1344       <td>Python script</td>
    1345     </tr>
    1346 
    1347     <tr>
    1348       <td class="mono">*tclsh* *wish*</td>
    1349 
    1350       <td class="mono">TCL::SCRIPT</td>
    1351 
    1352       <td>Tcl/Tk script</td>
    1353     </tr>
    1354   </table>
     1138  <dl>
     1139    <dt><samp>*Scr_* *Comp_* *IF_* *Suite_* *Interface_*</samp></dt>
     1140
     1141    <dd><code>SHELL::SCRIPT</code> Unix shell script, GEN-based project naming
     1142    conventions</dd>
     1143
     1144    <dt><samp>*List_*</samp></dt>
     1145
     1146    <dd><code>SHELL::SCRIPT::GENLIST</code> Unix shell script, GEN list
     1147    file</dd>
     1148
     1149    <dt><samp>*Sql_*</samp></dt>
     1150
     1151    <dd><code>SCRIPT::SQL</code> SQL script, GEN-based project naming
     1152    conventions</dd>
     1153  </dl>
     1154
     1155  <p>The following is a list of supported <code>#!</code> line patterns and
     1156  their associated types:</p>
     1157
     1158  <dl>
     1159    <dt><samp>*sh* *ksh* *bash* *csh*</samp></dt>
     1160
     1161    <dd><code>SHELL::SCRIPT</code> Unix shell script</dd>
     1162
     1163    <dt><samp>*perl*</samp></dt>
     1164
     1165    <dd><code>PERL::SCRIPT</code> Perl script</dd>
     1166
     1167    <dt><samp>*python*</samp></dt>
     1168
     1169    <dd><code>PYTHON::SCRIPT</code> Python script</dd>
     1170
     1171    <dt><samp>*tclsh* *wish*</samp></dt>
     1172
     1173    <dd><code>TCL::SCRIPT</code> Tcl/Tk script</dd>
     1174  </dl>
    13551175
    13561176  <p>The build system allows you to add or modify the register for input file
    1357   extensions and their associated type using the INFILE_EXT::&lt;ext&gt;
    1358   declaration, where &lt;ext&gt; is a file name extension without the leading
    1359   dot. For example, in an extract configuration file, you may have:</p>
    1360 
    1361   <table class="pad" summary="build_example8" border="1" width="100%">
    1362     <tr>
    1363       <th>Build configuration example 8 - add/modify input file extension
    1364       types</th>
    1365     </tr>
    1366 
    1367     <tr>
    1368       <td>
    1369         <pre>
    1370 cfg::type             ext
    1371 cfg::version          1.0
    1372 
    1373 bld::infile_ext::foo  CPP::INCLUDE                # line 4
    1374 bld::infile_ext::bar  FORTRAN::FORTRAN9X::INCLUDE # line 5
     1177  extensions and their associated type using the
     1178  <code>INFILE_EXT::&lt;ext&gt;</code> declaration, where &lt;ext&gt; is a file
     1179  name extension without the leading dot. If file extension alone is
     1180  insufficient for defining the type of your source file, you can use the
     1181  <code>SRC_TYPE::&lt;pcks&gt;</code> declaration, (where &lt;pcks&gt; is the
     1182  package name of the source file). For example, in an extract configuration
     1183  file, you may have:</p>
     1184  <pre id="example_8">
     1185# Example 8
     1186# ----------------------------------------------------------------------
     1187cfg::type                ext
     1188cfg::version             1.0
     1189
     1190bld::infile_ext::foo     CPP::INCLUDE                # line 4
     1191bld::infile_ext::bar     FORTRAN::FORTRAN9X::INCLUDE # line 5
     1192bld::src_type::egg/ham.f FORTRAN::FORTRAN9X::INCLUDE # line 6
    13751193
    13761194# ... some other declarations ...
    13771195</pre>
    1378       </td>
    1379     </tr>
    1380   </table>
    13811196
    13821197  <p>Here is an explanation of what each line does:</p>
    13831198
    13841199  <ul>
    1385     <li>line 4: this line registers the extension ".foo" to be of type
    1386     "CPP::INCLUDE". This means that any input files with ".foo"
    1387     extension will be treated as if they are pre-processor header files.</li>
    1388 
    1389     <li>line 5: this line registers the extension ".bar" to be of type
    1390     "FORTRAN::FORTRAN9X::INCLUDE". This means that any input file
    1391     with ".bar" extension will be treated as if they are Fortran 9X INCLUDE
    1392     files.</li>
     1200    <li><dfn>line 4</dfn>: this line registers the extension <samp>.foo</samp>
     1201    to be of type <code>CPP::INCLUDE</code>. This means that any input files
     1202    with <samp>.foo</samp> extension will be treated as if they are
     1203    pre-processor header files.</li>
     1204
     1205    <li><dfn>line 5</dfn>: this line registers the extension <samp>.bar</samp>
     1206    to be of type <code>FORTRAN::FORTRAN9X::INCLUDE</code>. This means that any
     1207    input file with <samp>.bar</samp> extension will be treated as if they are
     1208    Fortran 9X INCLUDE files.</li>
     1209
     1210    <li><dfn>line 6</dfn>: this line declares the type for the source file in
     1211    the package <samp>egg::ham.f</samp> to be
     1212    <code>FORTRAN::FORTRAN9X::INCLUDE</code>. Without this declaration, this
     1213    file would normally be given the type <code>FORTRAN::SOURCE</code>.</li>
    13931214  </ul>
    13941215
    1395   <p>The INFILE_EXT declarations deal with extensions of input files. There is
    1396   also a OUTFILE_EXT::&lt;type&gt; declaration that deals with extensions of
    1397   output files. The declaration is opposite that of INFILE_EXT. The file
    1398   &lt;type&gt; is now declared with the label, and the extension is declared
    1399   as the value. It is worth noting that OUTFILE_EXT declarations use very
    1400   different syntax for &lt;type&gt;, and the declared extension must include
    1401   the leading dot. For a list of output types used by the build system,
    1402   please see the <a href="annex_bld_cfg.html#outfile-ext-types">output file
    1403   extension types table</a> in the <a href="annex_bld_cfg.html">
    1404   Annex: Declarations in FCM build configuration file</a>.
    1405   An example is given below:</p>
    1406 
    1407   <table class="pad" summary="build_example9" border="1" width="100%">
    1408     <tr>
    1409       <th>Build configuration example 9 - modify output file extensions</th>
    1410     </tr>
    1411 
    1412     <tr>
    1413       <td>
    1414         <pre>
     1216  <p>The <code>INFILE_EXT</code> declarations deal with extensions of input
     1217  files. There is also a <code>OUTFILE_EXT::&lt;type&gt;</code> declaration
     1218  that deals with extensions of output files. The declaration is opposite that
     1219  of <code>INFILE_EXT</code>. The file &lt;type&gt; is now declared with the
     1220  label, and the extension is declared as the value. It is worth noting that
     1221  <code>OUTFILE_EXT</code> declarations use very different syntax for
     1222  &lt;type&gt;, and the declared extension must include the leading dot. For a
     1223  list of output types used by the build system, please see the <a href=
     1224  "annex_bld_cfg.html#outfile-ext-types">output file extension types table</a>
     1225  in the <a href="annex_bld_cfg.html">Annex: Declarations in FCM build
     1226  configuration file</a>. An example is given below:</p>
     1227  <pre id="example_9">
     1228# Example 9
     1229# ----------------------------------------------------------------------
    14151230cfg::type                   ext
    14161231cfg::version                1.0
    14171232
    1418 bld::outfile_ext::mk        .rule  # line 4
    1419 bld::outfile_ext::mod       .MOD   # line 5
    1420 bld::outfile_ext::interface .intfb # line 6
     1233bld::outfile_ext::mod       .MOD   # line 4
     1234bld::outfile_ext::interface .intfb # line 5
    14211235
    14221236# ... some other declarations ...
    14231237</pre>
    1424       </td>
    1425     </tr>
    1426   </table>
    14271238
    14281239  <p>Here is an explanation of what each line does:</p>
    14291240
    14301241  <ul>
    1431     <li>line 4: this line modifies the extension of output <em>Makefile</em>
    1432     fragments, output of the dependency scanner, from the default ".mk" to
    1433     ".rule".</li>
    1434 
    1435     <li>line 5: this line modifies the extension of compiled Fortran 9X module
    1436     information files from the default ".mod" to ".MOD".</li>
    1437 
    1438     <li>line 6: this line modifies the extension of INCLUDE Fortran 9X
    1439     interface block files from the default ".interface" to ".intfb".</li>
     1242    <li><dfn>line 4</dfn>: this line modifies the extension of compiled Fortran
     1243    9X module information files from the default <samp>.mod</samp> to
     1244    <samp>.MOD</samp>.</li>
     1245
     1246    <li><dfn>line 5</dfn>: this line modifies the extension of INCLUDE Fortran
     1247    9X interface block files from the default <samp>.interface</samp> to
     1248    <samp>.intfb</samp>.</li>
    14401249  </ul>
    14411250
    … …  
    14441253  full-build mode to avoid unexpected behaviour.</p>
    14451254
    1446   <h3><a name="advanced_incremental">Incremental build based on a pre-compiled
    1447   build</a></h3>
    1448 
    1449   <p>As you can perform incremental extractions against pre-extracted source
    1450   code, you can perform incremental builds against pre-compiled builds. The
    1451   very same USE statement can be used to declare a build, which the current
    1452   build will depend on. The only difference is that the declared location must
    1453   contain a valid build configuration file. In fact, if you use the extract
    1454   system to obtain your build configuration file, any USE declarations in the
    1455   extract configuration file will also be USE declarations in the output
    1456   build configuration file.</p>
    1457 
    1458   <p>By declaring a USE statement, the current build automatically inherits
    1459   settings from the pre-compiled build. The following points are worth
    1460   noting:</p>
     1255  <h3 id="advanced_inherit">Inherit from a previous build</h3>
     1256
     1257  <p>As you can inherit from previous extracts, you can inherit from previous
     1258  builds. The very same <code>USE</code> statement can be used to declare a
     1259  build, which the current build will depend on. The only difference is that
     1260  the declared location must contain a valid build configuration file. In fact,
     1261  if you use the extract system to obtain your build configuration file, any
     1262  <code>USE</code> declarations in the extract configuration file will also be
     1263  <code>USE</code> declarations in the output build configuration file.</p>
     1264
     1265  <p>By declaring a previous build with a <code>USE</code> statement, the
     1266  current build automatically inherits settings from it. The following points
     1267  are worth noting:</p>
    14611268
    14621269  <ul>
    1463     <li>
    1464       Build targets are not normally inherited. However, you can switch on
    1465       inheritance of build targets using an INHERIT::TARGET declaration, such
    1466       as:
     1270    <li>Build targets are not normally inherited. However, you can switch on
     1271    inheritance of build targets using an <code>INHERIT::TARGET</code>
     1272    declaration, such as:
    14671273      <pre>
    1468 inherit::target  1
     1274inherit::target  true
    14691275</pre>
    14701276    </li>
    14711277
    1472     <li> The build root directory and its sub-directories of the pre-compiled
    1473     build are placed into the search paths. For example, if we have a
    1474     pre-compiled build at "/path/to/pre/compiled", and it is used by an
    1475     incremental build at "/path/to/incremental", the search path of executable
    1476     files will become "/path/to/incremental/bin:/path/to/pre/compiled/bin", so
    1477     that the "bin/" sub-directory of the incremental build is searched before
    1478     the "bin/" sub-directory of the pre-compiled build. If two or more USE
    1479     statements are declared, the USE statement declared last will have higher
    1480     priority. For example, if the current build is "C", and it USEs build "A"
    1481     before build "B", the search path will be "C:B:A".</li>
    1482 
    1483     <li>
    1484       Sub-package source directories are inherited by default. If a source
    1485       directory is declared in the current build that has the same sub-package
    1486       name as a source directory of the pre-compiled build, any source files in
    1487       the source directory of the current build will override those in the
    1488       source directory of the pre-compiled build. Any source files missing
    1489       from the source directory of the current build will be taken from the
    1490       source directory of the pre-compiled build.
    1491 
    1492       <p>For example, if build "B" USEs build "A", and both of them have a
    1493       sub-package called "basic::element". In build "A", the sub-package
    1494       contains the source files "earth.f90", "wind.f90" and "water.f90". In
    1495       build "B", the sub-package contains "earth.f90" and "fire.f90". When the
    1496       system searches for source files, it will look for source files in "B"
    1497       before "A". Therefore, the source file "earth.f90" in "B" will override
    1498       that of "A", and the files used for the build will be "earth.f90" and
    1499       "fire.f90" from "B" and "wind.f90" and "water.f90" from "A".</p>
    1500      
    1501       <p>You can switch off inheritance of source directories using an
    1502       INHERIT::SRC declaration.  This declaration can be suffixed with the
    1503       name of a sub-package. In such case, the declaration applies only to the
    1504       inheritance of the sub-package. Otherwise, it applies to all source
    1505       directories. For example:</p>
    1506 
     1278    <li>The build root directory and its sub-directories of the inherited build
     1279    are placed into the search paths. For example, if we have an inherited
     1280    build at <samp>/path/to/inherited</samp>, and it is used by a build at
     1281    <samp>/path/to/my_build</samp>, the search path of executable files will
     1282    become <samp>/path/to/my_build/bin:/path/to/inherited/bin</samp>, so that
     1283    the <samp>bin/</samp> sub-directory of the current build is searched before
     1284    the <samp>bin/</samp> sub-directory of the inherited build. If two or more
     1285    <code>USE</code> statements are declared, the <code>USE</code> statement
     1286    declared last will have higher priority. For example, if the current build
     1287    is <var>C</var>, and it USEs build <var>A</var> before build <var>B</var>,
     1288    the search path will be <samp>C:B:A</samp>.</li>
     1289
     1290    <li>Source files are inherited by default. If a source file is declared in
     1291    the current build that has the same package name as a source file of the
     1292    inherited build, it will override that in the inherited build. Any source
     1293    files missing from the current build will be taken from the inherited
     1294    build.
     1295
     1296      <p>You can switch off inheritance of source files using an
     1297      <code>INHERIT::SRC</code> declaration. This declaration can be suffixed
     1298      with the name of a sub-package. In such case, the declaration applies
     1299      only to the inheritance of the sub-package. Otherwise, it applies
     1300      globally. For example:</p>
    15071301      <pre>
    1508 # Switch off inheritance of source directories in the "gen" sub-package
    1509 inherit::src::gen  0
     1302# Switch off inheritance of source files in the <samp>gen</samp> sub-package
     1303inherit::src::gen  false
    15101304</pre>
    15111305    </li>
    15121306
    1513     <li>All build tools are automatically inherited. If the same tool is
    1514     declared in the current incremental build, it overrides the declaration in
    1515     the pre-compiled build.</li>
    1516 
    1517     <li>"PP", "EXCL_DEP", "INFILE_EXT" and "OUTFILE_EXT" declarations are
    1518     inherited using a similar mechanism as build tool declarations.</li>
     1307    <li><code>BLOCKDATA</code>, <code>DEP</code>, <code>EXCL_DEP</code>,
     1308    <code>EXE_DEP</code>, <code>INFILE_EXT</code>, <code>LIB</code>,
     1309    <code>OUTFILE_EXT</code>, <code>PP</code>, <code>TOOL</code> and
     1310    <code>SRC_TYPE</code> declarations are automatically inherited. If the same
     1311    setting is declared in the current incremental build, it overrides the
     1312    inherited declaration.</li>
    15191313  </ul>
    15201314
    1521   <p>As an example, suppose we have already performed an extract and build based
    1522   on the configuration in example 2, we can set up an extract configuration
    1523   file as follows:</p>
    1524 
    1525   <table class="pad" summary="build_example10" border="1" width="100%">
    1526     <tr>
    1527       <th>Build configuration example 10 - "USE" a pre-compiled
    1528       build</th>
    1529     </tr>
    1530 
    1531     <tr>
    1532       <td>
    1533         <pre>
     1315  <p>As an example, suppose we have already performed an extract and build
     1316  based on the configuration in <a href="#example_2">example 2</a>, we can set
     1317  up an extract configuration file as follows:</p>
     1318  <pre id="example_10">
     1319# Example 10
     1320# ----------------------------------------------------------------------
    15341321cfg::type            ext
    15351322cfg::version         1.0
    … …  
    15371324use                  $HOME/example               # line 4
    15381325
    1539 dest::rootdir        $HOME/example9              # line 6
    1540 
    1541 bld::inherit::target 1                           # line 8
     1326dest                 $HOME/example10             # line 6
     1327
     1328bld::inherit::target true                        # line 8
    15421329bld::target          ham.exe egg.exe             # line 9
    15431330
    … …  
    15471334# ... and other declarations for repositories and source directories ...
    15481335</pre>
    1549       </td>
    1550     </tr>
    1551   </table>
    15521336
    15531337  <p>Here is an explanation of what each line does:</p>
    15541338
    15551339  <ul>
    1556     <li>line 4: this line declares a previous extraction at
    1557     "$HOME/example" which the current extraction will be based on. The
    1558     same line will be written to the output build configuration file at
    1559     "$HOME/example9/cfg/bld.cfg". The subsequent build will then be
    1560     based on the build at "$HOME/example".</li>
    1561 
    1562     <li>line 6: this declares the destination root directory of the current
    1563     extraction, which will become the root directory of the current build.
     1340    <li><dfn>line 4</dfn>: this line declares a previous extract at
     1341    <samp>$HOME/example</samp> which the current extract will inherit from. The
     1342    same line will be written to the output build configuration file. The
     1343    subsequent build will then inherit from the build at
     1344    <samp>$HOME/example</samp>.</li>
     1345
     1346    <li><dfn>line 6</dfn>: this declares the destination root directory of the
     1347    current extract, which will become the root directory of the current build.
    15641348    Search paths of the build sub-directories will be set automatically. For
    15651349    example, the search path for executable files created by the current build
    1566     will be "$HOME/example9/bin:$HOME/example/bin".</li>
    1567 
    1568     <li>line 8: this line switches on inheritance of build targets. The build
    1569     targets in example 1, i.e. "foo.exe" and "bar.exe" will be built as part
    1570     of the current build.</li>
    1571 
    1572     <li>line 9: this declares two new build targets "ham.exe" and "egg.exe" to
    1573     be added to the inherited ones. The default build targets of the current
    1574     build will now be "foo.exe", "bar.exe", "ham.exe" and "egg.exe".</li>
    1575 
    1576     <li>line 11-12: these lines modify options used by the Fortran and the C
    1577     compilers, overriding those inherited from example 1.</li>
     1350    will be <samp>$HOME/example10/bin:$HOME/example/bin</samp>.</li>
     1351
     1352    <li><dfn>line 8</dfn>: this line switches on inheritance of build targets.
     1353    The build targets in <a href="#example_1">example 1</a>, i.e.
     1354    <samp>foo.exe</samp> and <samp>bar.exe</samp> will be built as part of the
     1355    current build.</li>
     1356
     1357    <li><dfn>line 9</dfn>: this declares two new build targets
     1358    <samp>ham.exe</samp> and <samp>egg.exe</samp> to be added to the inherited
     1359    ones. The default build targets of the current build will now be
     1360    <samp>foo.exe</samp>, <samp>bar.exe</samp>, <samp>ham.exe</samp> and
     1361    <samp>egg.exe</samp>.</li>
     1362
     1363    <li><dfn>line 11-12</dfn>: these lines modify options used by the Fortran
     1364    and the C compilers, overriding those inherited from <a href=
     1365    "#example_1">example 1</a>.</li>
    15781366  </ul>
    15791367
    1580   <h3><a name="advanced_pckcfg">Using a package configuration file</a></h3>
    1581 
    1582   <p>It is recognised that the build system needs to be able to work with code
    1583   that is not designed to work with the automatic dependency scanner. There are
    1584   various techniques which can be used to achieve this, some of which are
    1585   already described. However, it should be noted that these techniques are
    1586   simply designed to allow code to be successfully built. They will not
    1587   necessarily result in a good environment for developing such code, since for
    1588   example, dependencies need to be manually maintained by the developer.</p>
    1589 
    1590   <p>The final technique is the package configuration file. The package
    1591   configuration file is a special source file to inform the build system about
    1592   any additional information of the source files in the package. It must be a
    1593   file called "@PACKAGE.cfg" in a source directory. For a full list of available
    1594   declarations in the package configuration file, please refer to the <a
    1595   href="annex_pck_cfg.html">Annex: Declarations in FCM build package
    1596   configuration file</a>.</p>
    1597 
    1598   <p>The following is an example of how a package configuration file can be
    1599   used to provide additional information to the build system for a source
    1600   file:</p>
    1601 
    1602   <table class="pad" summary="package_example1" border="1" width="100%">
    1603     <tr>
    1604       <th>Package configuration example 1 - dependency information for a
    1605       source file</th>
    1606     </tr>
    1607 
    1608     <tr>
    1609       <td>
    1610         <pre>
    1611 type::MyFortranProg.f90    FORTRAN::FORTRAN9X::SOURCE::PROGRAM # line 1
    1612 scan::MyFortranProg.f90    0                                   # line 2
    1613 intname::MyFortranProg.f90 myprog                              # line 3
    1614 target::MyFortranProg.f90  hello_world                         # line 4
    1615 
    1616 dep::MyFortranProg.f90     USE::YourFortranMod                 # line 6
    1617 dep::MyFortranProg.f90     INTERFACE::HerFortran.interface     # line 7
    1618 dep::MyFortranProg.f90     INC::HisFortranInc.inc              # line 8
    1619 dep::MyFortranProg.f90     H::TheirHeader.h                    # line 9
    1620 dep::MyFortranProg.f90     OBJ::ItsObject.o                    # line 10
    1621 
    1622 # ... some other declarations ...
    1623 </pre>
    1624       </td>
    1625     </tr>
    1626   </table>
    1627 
    1628   <p>Here is an explanation of what each line does:</p>
    1629 
    1630   <ul>
    1631     <li>line 1: this declares a source file "MyFortranProg.f90" in the package
    1632     of type "FORTRAN::FORTRAN9X::SOURCE::PROGRAM", i.e. a Fortran 9X source
    1633     file containing a main program. The list of type flags used in the value
    1634     is the same list of type flags used in the INFILE_EXT declaration of a
    1635     build configuration file. For a list of  these flags, please see the <a
    1636     href="annex_bld_cfg.html#infile-ext-types">Input file extension type flags
    1637     table</a> in the <a href="annex_bld_cfg.html">
    1638     Annex: Declarations in FCM build configuration file</a>.</li>
    1639 
    1640     <li>line 2: this declaration switches off (0) automatic dependency scan for
    1641     this source file. If this switch is not declared, it is automatically set
    1642     to on (1) for a source file. If the switch is on, the dependency scanner
    1643     will scan the source file for further dependencies. Otherwise, dependency
    1644     information for this source file will only be read from this configuration
    1645     file.</li>
    1646 
    1647     <li>line 3: this declares the internal name of the source file to be
    1648     "myprog". If this is not set and the dependency scanner is switched on,
    1649     the internal name of the source file will be taken from the first program
    1650     unit of the source file. The resulting object file will be named after
    1651     the internal name, plus the ".o" extension. If internal name is not set
    1652     and cannot be determined automatically, the default is to use the root
    1653     name of the source file to name the object file.</li>
    1654 
    1655     <li>line 4: this declares the executable target name of a main program.
    1656     This declaration is only used when the source file contains a main
    1657     program. If the target name is not set, the name of the executable will be
    1658     named after the root name of the source file plus the ".exe" extension. In
    1659     the above example, the executable will be named "hello_world".</li>
    1660 
    1661     <li>line 6-10: these lines declare the dependencies of the source file.
    1662     The syntax of the values are exactly the same as those used in the
    1663     EXCL_DEP declarations in the build configuration file. For a list of these
    1664     flags, please see the <a
    1665     href="annex_bld_cfg.html#dependency-types">dependency types table</a> in
    1666     the <a href="annex_bld_cfg.html">Annex:
    1667     Declarations in FCM build configuration file</a>. In the example,
    1668     the source file is dependent on a Fortran module called "YourFortranMod",
    1669     a Fortran INCLUDE interface block file called "HerFortran.interface", a
    1670     Fortran INCLUDE file called "HistFortran.inc, a pre-processor header file
    1671     called "TheirHeader.h", and an object file called "ItsObject.o".</li>
    1672   </ul>
    1673 
    1674   <h3><a name="advanced_data">Building data files</a></h3>
     1368  <dl>
     1369    <dt>Build inheritance limitation: handling of include files</dt>
     1370
     1371    <dd>
     1372      <p>The build system uses the compiler/pre-processor's <code>-I</code>
     1373      option to specify the search path for include files. For example, it uses
     1374      the option to specify the <samp>inc/</samp> sub-directories of the
     1375      current build and its inherited build.</p>
     1376
     1377      <p>However, some compilers/pre-processors (e.g. <code>cpp</code>) search
     1378      for include files from the container directory of the source file before
     1379      searching for the paths specified by the <code>-I</code> options. This
     1380      behaviour may cause the build to behave incorrectly.</p>
     1381
     1382      <p>Consider a source file <samp>egg/hen.c</samp> that includes
     1383      <samp>fried.h</samp>. If the directory structure looks like:</p>
     1384      <pre>
     1385# Sources in inherited build:
     1386egg/hen.c
     1387egg/fried.h
     1388
     1389# Sources in current build:
     1390egg/fried.h
     1391</pre>
     1392
     1393      <p>The system will correctly identify that <samp>fried.h</samp> is out of
     1394      date, and trigger a re-compilation of <samp>egg/hen.c</samp>. However, if
     1395      the compiler searches for the include files from the container directory
     1396      of the source file first, it will wrongly use the include file in the
     1397      inherited build instead of the current one.</p>
     1398
     1399      <p>Some compilers (e.g. <code>gfortran</code>) do not behave this way and
     1400      others (e.g. <code>ifort</code>) have options to prevent include file
     1401      search in the container directory of the source file. If you are using
     1402      such a compiler you can avoid the problem for Fortran compilation
     1403      although this does not fix the problem entirely if you have switched on
     1404      the pre-processing stage. Otherwise you may have to work around the
     1405      problem, (e.g. by making a comment change in the source file, or by not
     1406      using an inherited build at all).</p>
     1407    </dd>
     1408  </dl>
     1409
     1410  <h3 id="advanced_data">Building data files</h3>
    16751411
    16761412  <p>While the usual targets to be built are the executables associated with
    16771413  source files containing main programs, libraries or scripts, the build system
    1678   also allows you to build "data" files. All files with no registered type are
    1679   considered to be "data" files.  For each sub-package, there is an automatic
    1680   target for copying all "data" files to the "etc/" sub-directory of the build
    1681   root. The name of the target has the form "&lt;pcks&gt;.etc", where
    1682   &lt;pcks&gt; is the name of the sub-package (with package names delimited by
    1683   the double underscore "__"). For example, the target name for sub-package
    1684   "foo::bar" is "foo__bar.etc". This target is particularly useful for copying,
    1685   say, all namelists in a sub-package to the "etc/" sub-directory of the build
    1686   root.</p>
    1687 
    1688   <p>At the end of a successful build, if the "etc/" sub-directory is not empty,
    1689   the "fcm_env.ksh" script will export the environment variable FCM_ETCDIR to
    1690   point to the "etc/" sub-directory. You should be able to use this environment
    1691   variable to locate your data files.</p>
    1692 
    1693   <h2><a name="verbose">Diagnostic verbose level</a></h2>
     1414  also allows you to build <em>data</em> files. All files with no registered
     1415  type are considered to be <em>data</em> files. For each container
     1416  sub-package, there is an automatic target for copying all <em>data</em> files
     1417  to the <samp>etc/</samp> sub-directory of the build root. The name of the
     1418  target has the form <code>&lt;pcks&gt;.etc</code>, where &lt;pcks&gt; is the
     1419  name of the sub-package (with package names delimited by the double
     1420  underscore <code>__</code>). For example, the target name for sub-package
     1421  <samp>foo/bar</samp> is <samp>foo__bar.etc</samp>. This target is
     1422  particularly useful for copying, say, all namelists in a sub-package to the
     1423  <samp>etc/</samp> sub-directory of the build root.</p>
     1424
     1425  <p>At the end of a successful build, if the <samp>etc/</samp> sub-directory
     1426  is not empty, the <samp>fcm_env.sh</samp> script will export the environment
     1427  variable <var>FCM_ETCDIR</var> to point to the <samp>etc/</samp>
     1428  sub-directory. You should be able to use this environment variable to locate
     1429  your data files.</p>
     1430
     1431  <h2 id="verbose">Diagnostic verbose level</h2>
    16941432
    16951433  <p>The amount of diagnostic messages generated by the build system is
    … …  
    16991437  diagnostic messages, you can set the verbose level to 2 or 3. You can modify
    17001438  the verbose level in two ways. The first way is to set the environment
    1701   variable FCM_VERBOSE to the desired verbose level. The second way is to
    1702   invoke the build system with the "-v &lt;level&gt;" option. (If set, the
    1703   command line option overrides the environment variable.)</p>
     1439  variable <var>FCM_VERBOSE</var> to the desired verbose level. The second way
     1440  is to invoke the build system with the <code>-v &lt;level&gt;</code> option.
     1441  (If set, the command line option overrides the environment variable.)</p>
    17041442
    17051443  <p>The following is a list of diagnostic output at each verbose level:</p>
    17061444
    1707   <table class="pad" summary="List of diagnostic verbose output" border="1">
    1708     <tr>
    1709       <th>Verbose level</th>
    1710 
    1711       <th>Possible output</th>
    1712     </tr>
    1713 
    1714     <tr>
    1715       <th>0</th>
    1716 
    1717       <td>
    1718         <ul>
    1719           <li>Report the time taken at the end of each stage of the build
    1720           process.</li>
    1721 
    1722           <li>Run the <em>make</em> command in silent mode.</li>
    1723         </ul>
    1724       </td>
    1725     </tr>
    1726 
    1727     <tr>
    1728       <th>1</th>
    1729 
    1730       <td>
    1731         <ul>
    1732           <li>Everything at verbose level 0.</li>
    1733 
    1734           <li>Report the name of the build configuration file.</li>
    1735 
    1736           <li>Report date/time at the beginning of each stage of the build
    1737           process.</li>
    1738 
    1739           <li>Report removed directories.</li>
    1740 
    1741           <li>Report number of pre-processed files.</li>
    1742 
    1743           <li>Report number of generated F9X interface files.</li>
    1744 
    1745           <li>Report number of sub-packages that have source files scanned
    1746           for dependencies.</li>
    1747 
    1748           <li>Report number of generated/updated sub-package <em>make</em>
    1749           rule fragment files.</li>
    1750 
    1751           <li>Report name of updated <em>Makefile</em>.</li>
    1752 
    1753           <li>Print compiler/linker commands.</li>
    1754 
    1755           <li>Report total time.</li>
    1756         </ul>
    1757       </td>
    1758     </tr>
    1759 
    1760     <tr>
    1761       <th>2</th>
    1762 
    1763       <td>
    1764         <ul>
    1765           <li>Everything at verbose level 1.</li>
    1766 
    1767           <li>For incremental build in archive mode, report the commands used
    1768           to extract the archives.</li>
    1769 
    1770           <li>Report creation and removal of directories.</li>
    1771 
    1772           <li>Report pre-processor commands.</li>
    1773 
    1774           <li>Report number of files scanned for dependency in each
    1775           sub-package.</li>
    1776 
    1777           <li>Report names of generated/updated sub-package <em>make</em> rule
    1778           fragment files.</li>
    1779 
    1780           <li>Print compiler/linker commands with timestamps.</li>
    1781 
    1782           <li>Print usage of the runtime environment set up script.</li>
    1783         </ul>
    1784       </td>
    1785     </tr>
    1786 
    1787     <tr>
    1788       <th>3</th>
    1789 
    1790       <td>
    1791         <ul>
    1792           <li>Everything at verbose level 2.</li>
    1793 
    1794           <li>Report update of dummy files.</li>
    1795 
    1796           <li>Report all shell commands.</li>
    1797 
    1798           <li>Report pre-processor commands with timestamps.</li>
    1799 
    1800           <li>If F9X interface is generated by <em>f90aib</em>, print commands
    1801           with timestamps.</li>
    1802 
    1803           <li>If F9X interface is generated by ECMWF code, report start
    1804           date/time and time taken to generate each interface file.</li>
    1805 
    1806           <li>Report start date/time and time taken of dependency scan for each
    1807           source file.</li>
    1808 
    1809           <li>Run <em>make</em> on normal mode (as opposed to silent mode).</li>
    1810 
    1811           <li>Report start date/time and time taken of <em>make</em>
    1812           commands.</li>
    1813         </ul>
    1814       </td>
    1815     </tr>
    1816   </table>
    1817 
    1818   <h2><a name="overview">Overview of the build process</a></h2>
     1445  <dl>
     1446    <dt>Level 0</dt>
     1447
     1448    <dd>
     1449      <ul>
     1450        <li>Report the time taken at the end of each stage of the build
     1451        process.</li>
     1452
     1453        <li>Run the <code>make</code> command in silent mode.</li>
     1454      </ul>
     1455    </dd>
     1456
     1457    <dt>Level 1</dt>
     1458
     1459    <dd>
     1460      <ul>
     1461        <li>Everything at verbose level 0.</li>
     1462
     1463        <li>Report the name of the build configuration file.</li>
     1464
     1465        <li>Report the location of the build destination.</li>
     1466
     1467        <li>Report date/time at the beginning of each stage of the build
     1468        process.</li>
     1469
     1470        <li>Report removed directories.</li>
     1471
     1472        <li>Report number of pre-processed files.</li>
     1473
     1474        <li>Report number of generated F9X interface files.</li>
     1475
     1476        <li>Report number of source files scanned for dependencies.</li>
     1477
     1478        <li>Report name of updated <samp>Makefile</samp>.</li>
     1479
     1480        <li>Print compiler/linker commands.</li>
     1481
     1482        <li>Report total time.</li>
     1483      </ul>
     1484    </dd>
     1485
     1486    <dt>Level 2</dt>
     1487
     1488    <dd>
     1489      <ul>
     1490        <li>Everything at verbose level 1.</li>
     1491
     1492        <li>For incremental build in archive mode, report the commands used to
     1493        extract the archives.</li>
     1494
     1495        <li>Report creation and removal of directories.</li>
     1496
     1497        <li>Report pre-processor commands.</li>
     1498
     1499        <li>Print compiler/linker commands with timestamps.</li>
     1500      </ul>
     1501    </dd>
     1502
     1503    <dt>Level 3</dt>
     1504
     1505    <dd>
     1506      <ul>
     1507        <li>Everything at verbose level 2.</li>
     1508
     1509        <li>Report update of dummy files.</li>
     1510
     1511        <li>Report all shell commands.</li>
     1512
     1513        <li>Report pre-processor commands with timestamps.</li>
     1514
     1515        <li>Report any F9X interface files generated.</li>
     1516
     1517        <li>Report number of lines and number of automatic dependencies for
     1518        each source file which is scanned.</li>
     1519
     1520        <li>Run <code>make</code> on normal mode (as opposed to silent
     1521        mode).</li>
     1522
     1523        <li>Report start date/time and time taken of <code>make</code>
     1524        commands.</li>
     1525      </ul>
     1526    </dd>
     1527  </dl>
     1528
     1529  <h2 id="overview">Overview of the build process</h2>
    18191530
    18201531  <p>The FCM build process can be summarised in five stages. Here is a summary
    … …  
    18221533
    18231534  <ol>
    1824     <li><strong>Setup</strong>: in this first stage, the build system reads
    1825     and processes the configuration file. The source sub-directory is searched
    1826     recursively for source directories. For full builds, it ensures that the
    1827     sub-directories created by the build system are removed. For inherited
    1828     (i.e. pre-compiled) builds, it sets up the search paths for the
    1829     sub-directories, inherits the targets, source directories, etc. For
    1830     incremental builds, the system also works out whether the current list of
    1831     build tools have changed.</li>
    1832 
    1833     <li><strong>Pre-process</strong>: if any files in any source directories
    1834     require pre-processing, they will be pre-processed at this stage. The
    1835     resulting pre-processed source files will be sent to the "ppsrc/"
     1535    <li><dfn>Parse configuration and setup destination</dfn>: in this
     1536    pre-requisite stage, the build system parses the configuration file. The
     1537    <samp>src/</samp> sub-directory is searched recursively for source files.
     1538    For full builds, it ensures that the sub-directories and files created by
     1539    the build system are removed. If you invoke <code>fcm build</code> with a
     1540    <code>--clean</code> option, the system will not go any further.</li>
     1541
     1542    <li><dfn>Setup build</dfn>: in this first stage, the system determines
     1543    whether any settings have changed by using the cache. If so, the cache is
     1544    updated with the current settings.</li>
     1545
     1546    <li><dfn>Pre-process</dfn>: if any files in any source files require
     1547    pre-processing, they will be pre-processed at this stage. The resulting
     1548    pre-processed source files will be sent to the <samp>ppsrc/</samp>
    18361549    sub-directory of the build root.</li>
    18371550
    1838     <li><strong>Generate dependency</strong>: the system scans source files of
     1551    <li><dfn>Generate dependency</dfn>: the system scans source files of
    18391552    registered types for dependency information. For an incremental build, the
    18401553    information is only updated if a source file is changed. The system then
    1841     uses the information to write a <em>Makefile</em> for the main build. The
    1842     <em>Makefile</em> and any of its included fragments are generated in the
    1843     "bld/" sub-directory of the build root.</li>
    1844 
    1845     <li><strong>Generate interface</strong>: if there are Fortran 9X source
    1846     files with standalone subroutines and functions, the build system
    1847     generates interface blocks for them. The result of which will be written
    1848     to the interface files in the "inc/" sub-directory of the build root.</li>
     1554    uses the information to write a <samp>Makefile</samp> for the main
     1555    build.</li>
     1556
     1557    <li><dfn>Generate interface</dfn>: if there are Fortran 9X source files
     1558    with standalone subroutines and functions, the build system generates
     1559    interface blocks for them. The result of which will be written to the
     1560    interface files in the <samp>inc/</samp> sub-directory of the build
     1561    root.</li>
    18491562
    18501563    <li>
    1851       <strong>Make</strong>: the system invokes <em>make</em> on the
    1852       <em>Makefile</em> generated in the previous stage to perform the main
    1853       build. Following a build, the "root" directory of the build may contain
    1854       the following sub-directories (empty ones are removed automatically at the
    1855       end of the build process):
    1856 
    1857       <table summary="list of build sub-directories" border="1" width="100%">
    1858         <tr>
    1859           <th>Sub-directory</th>
    1860 
    1861           <th>Contents</th>
    1862 
    1863           <th>Note</th>
    1864         </tr>
    1865 
    1866         <tr>
    1867           <th>.cache/</th>
    1868 
    1869           <td>&lt;cache files&gt;</td>
    1870 
    1871           <td>used internally by FCM</td>
    1872         </tr>
    1873 
    1874         <tr>
    1875           <th>bin/</th>
    1876 
    1877           <td>&lt;executable binaries and scripts&gt;</td>
    1878 
    1879           <td>-</td>
    1880         </tr>
    1881 
    1882         <tr>
    1883           <th>bld/</th>
    1884 
    1885           <td>Makefile and &lt;Makefile include files&gt;</td>
    1886 
    1887           <td>-</td>
    1888         </tr>
    1889 
    1890         <tr>
    1891           <th>cfg/</th>
    1892 
    1893           <td>bld.cfg</td>
    1894 
    1895           <td>this directory is not changed by the build system</td>
    1896         </tr>
    1897 
    1898         <tr>
    1899           <th>done/</th>
    1900 
    1901           <td>&lt;dummy "done" files&gt;</td>
    1902 
    1903           <td>used internally by the Makefile generated by FCM</td>
    1904         </tr>
    1905 
    1906         <tr>
    1907           <th>etc/</th>
    1908 
    1909           <td>&lt;miscellaneous data files&gt;</td>
    1910 
    1911           <td>-</td>
    1912         </tr>
    1913 
    1914         <tr>
    1915           <th>flags/</th>
    1916 
    1917           <td>&lt;dummy "flags" files&gt;</td>
    1918 
    1919           <td>used internally by the Makefile generated by FCM</td>
    1920         </tr>
    1921 
    1922         <tr>
    1923           <th>inc/</th>
    1924 
    1925           <td>&lt;include files&gt;</td>
    1926 
    1927           <td>such as *.h, *.inc, *.interface and *.mod files</td>
    1928         </tr>
    1929 
    1930         <tr>
    1931           <th>lib/</th>
    1932 
    1933           <td>&lt;object library archives&gt;</td>
    1934 
    1935           <td>-</td>
    1936         </tr>
    1937 
    1938         <tr>
    1939           <th>obj/</th>
    1940 
    1941           <td>&lt;compiled object files&gt;</td>
    1942 
    1943           <td>-</td>
    1944         </tr>
    1945 
    1946         <tr>
    1947           <th>ppsrc/</th>
    1948 
    1949           <td>&lt;source directories with pre-processed files&gt;</td>
    1950 
    1951           <td>-</td>
    1952         </tr>
    1953 
    1954 
    1955         <tr>
    1956           <th>src/</th>
    1957 
    1958           <td>&lt;source directories&gt;</td>
    1959 
    1960           <td>this directory is not changed by the build system</td>
    1961         </tr>
    1962         <tr>
    1963           <th>tmp/</th>
    1964 
    1965           <td>&lt;temporary objects and binaries&gt;</td>
    1966 
    1967           <td>files generated by the compiler/linker may be left here</td>
    1968         </tr>
    1969       </table>
     1564      <dfn>Make</dfn>: the system invokes <code>make</code> on the
     1565      <samp>Makefile</samp> generated in the previous stage to perform the main
     1566      build. Following a build, the <em>root</em> directory of the build may
     1567      contain the following sub-directories (empty ones are removed
     1568      automatically at the end of the build process):
     1569
     1570      <dl>
     1571        <dt><samp>.cache/.bld/</samp></dt>
     1572
     1573        <dd>Cache files, used internally by FCM.</dd>
     1574
     1575        <dt><samp>bin/</samp></dt>
     1576
     1577        <dd>Executable binaries and scripts.</dd>
     1578
     1579        <dt><samp>cfg/</samp></dt>
     1580
     1581        <dd>Configuration files.</dd>
     1582
     1583        <dt><samp>done/</samp></dt>
     1584
     1585        <dd>Dummy <em>done</em> files used internally by the
     1586        <samp>Makefile</samp> generated by FCM.</dd>
     1587
     1588        <dt><samp>etc/</samp></dt>
     1589
     1590        <dd>Miscellaneous data files.</dd>
     1591
     1592        <dt><samp>flags/</samp></dt>
     1593
     1594        <dd>Dummy <em>flags</em> files used internally by the
     1595        <samp>Makefile</samp> generated by FCM.</dd>
     1596
     1597        <dt><samp>inc/</samp></dt>
     1598
     1599        <dd>Include files, such as <samp>*.h</samp>, <samp>*.inc</samp>,
     1600        <samp>*.interface</samp>, and <samp>*.mod</samp>.</dd>
     1601
     1602        <dt><samp>lib/</samp></dt>
     1603
     1604        <dd>Object library archives.</dd>
     1605
     1606        <dt><samp>obj/</samp></dt>
     1607
     1608        <dd>Compiled object files.</dd>
     1609
     1610        <dt><samp>ppsrc/</samp></dt>
     1611
     1612        <dd>Source directories with pre-processed files.</dd>
     1613
     1614        <dt><samp>src/</samp></dt>
     1615
     1616        <dd>Source directories. This directory is not changed by the build
     1617        system.</dd>
     1618
     1619        <dt><samp>tmp/</samp></dt>
     1620
     1621        <dd>Temporary objects and binaries. Files generated by the
     1622        compiler/linker may be left here.</dd>
     1623      </dl>
    19701624    </li>
    19711625  </ol>
    19721626
    1973   <script type="text/javascript" src="maintain.js">
    1974   </script>
     1627  </div>
     1628  </div>
     1629  </div>
     1630
     1631  <hr/>
     1632  <div class="container-fluid text-center">
     1633    <div class="row"><div class="col-md-12">
     1634    <address><small>
     1635      Copyright &copy; 2006-2021 British Crown (Met Office) &amp; Contributors.
     1636      <a href="http://www.metoffice.gov.uk">Met Office</a>.
     1637      See <a href="../etc/fcm-terms-of-use.html">Terms of Use</a>.<br />
     1638      This document is released under the British <a href=
     1639      "http://www.nationalarchives.gov.uk/doc/open-government-licence/" rel=
     1640      "license">Open Government Licence</a>.<br />
     1641    </small></address>
     1642    </div></div>
     1643  </div>
     1644
     1645  <script type="text/javascript" src="../etc/jquery.min.js"></script>
     1646  <script type="text/javascript" src="../etc/bootstrap/js/bootstrap.min.js"></script>
     1647  <script type="text/javascript" src="../etc/fcm.js"></script>
     1648  <script type="text/javascript" src="../etc/fcm-version.js"></script>
    19751649</body>
    19761650</html>
Note: See TracChangeset for help on using the changeset viewer.