source: CONFIG/publications/ICOLMDZORINCA_CO2_Transport_GMD_2023/INCA/tools/fcm/doc/user_guide/build.html @ 6610

Last change on this file since 6610 was 6610, checked in by acosce, 10 months ago

INCA used for ICOLMDZORINCA_CO2_Transport_GMD_2023
File size: 77.7 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3<html>
4<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">
11</head>
12
13<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>
19
20  <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>
29
30  <p>To invoke the build system, simply issue the command:</p>
31  <pre>
32fcm build
33</pre>
34
35  <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>
43
44  <p>If the root directory of the build does not exist, the system performs a
45  new full build at this directory. If a previous build already exists at this
46  directory, the system performs an incremental build. If a full (fresh) build
47  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>
57
58  <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>
62
63  <p>The build configuration file is the user interface of the build system. It
64  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
68  file</a>.</p>
69
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>
85cfg::type     bld                           # line 1
86cfg::version  1.0                           # line 2
87
88dir::root     $HOME/example                 # line 4
89
90target        foo.exe bar.exe               # line 6
91
92tool::fc      ifc                           # line 8
93tool::fflags  -O3                           # line 9
94tool::cc      gcc                           # line 10
95tool::cflags  -O3                           # line 11
96tool::ld      ifc                           # line 12
97tool::ldflags -O3 -L$(HOME)/lib -legg -lham # line 13
98</pre>
99      </td>
100    </tr>
101  </table>
102
103  <p>Here is an explanation of what each line does:</p>
104
105  <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>
137  </ul>
138
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"
173src::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>
183search_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>
214
215  <p>As mentioned earlier, you can obtain a build configuration file through
216  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>
228cfg::type          ext                           # line 1
229cfg::version       1.0                           # line 2
230
231dest::rootdir      $HOME/example                 # line 4
232
233bld::target        foo.exe bar.exe               # line 6
234
235bld::tool::fc      ifc                           # line 8
236bld::tool::fflags  -O3                           # line 9
237bld::tool::cc      gcc                           # line 10
238bld::tool::cflags  -O3                           # line 11
239bld::tool::ld      ifc                           # line 12
240bld::tool::ldflags -O3 -L$(HOME)/lib -legg -lham # line 13
241
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
250  destination root directory that will become the root directory of the build.
251  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 
272  <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
275  <pre>
276bld::exe_name::foo  bar
277</pre>
278
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>
290
291  <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
305  case-insensitive, sub-package names are case sensitive in the declarations.
306  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>
344cfg::type              ext
345cfg::version           1.0
346
347dest::rootdir          $HOME/example
348
349bld::target            foo.exe bar.exe
350
351bld::tool::fc          ifc
352bld::tool::fflags      -O3    # line 9
353bld::tool::cc          gcc
354bld::tool::cflags      -O3
355bld::tool::ld          ifc
356bld::tool::ldflags     -L$(HOME)/lib -legg -lham
357
358bld::tool::fflags::ops -O1 -C # line 15
359bld::tool::fflags::gen -O2    # line 16
360
361# ... and other declarations for repositories and source directories ...
362</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
450  configuration file &gt; list of tools</a>.</p>
451
452  <h3><a name="basic_interface">Automatic Fortran 9X interface block</a></h3>
453
454  <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
468  <pre>
469bld::tool::interface  program # The default is "file"
470</pre>
471
472  <p>In such case, the root name of the interface file will be named in lower
473  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
478  Type</a>.</p>
479 
480  <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
486  <pre>
487INCLUDE 'foo.interface'
488</pre>
489
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
505  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
510  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>
521# This is an EXTRACT configuration file ...
522
523# ... some other declarations ...
524
525bld::tool::geninterface       f90aib # line 5
526bld::tool::geninterface::foo  ECMWF  # line 6
527bld::tool::geninterface::bar  none   # line 7
528
529# ... some other declarations ...
530</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>
540
541  <p>Switching off the interface block generator can be useful in many
542  circumstances. For example, if the interface block is already provided
543  manually within the source tree, or if the interface block is never used by
544  other program units, it is worth switching off the interface generator for
545  the source file to speed up the build process.</p>
546
547  <h3><a name="basic_dependency">Automatic dependency</a></h3>
548
549  <p>The build system has a built-in dependency scanner, which works out the
550  dependency relationship between source files, so that they can be built in
551  the correct order. The system scans all source files of known types for all
552  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
555  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
564  automatically detected by the current system:</p>
565
566  <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
596    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>
608  </ul>
609
610  <p>If you want your code to be built automatically by the FCM build system,
611  you should also design your code to conform to the following rules:</p>
612
613  <ol>
614    <li>Single compilable program unit, (i.e. program, subroutine, function or
615    module), per file.</li>
616
617    <li>Unique name for each compilable program unit.</li>
618
619    <li>Always supply an interface for subroutines and functions, i.e.:
620      <ul>
621        <li>Put them in modules.</li>
622
623        <li>Put them in the CONTAINS section within the main program unit.</li>
624
625        <li>Use interface files.</li>
626      </ul>
627    </li>
628
629    <li>If interface files are used, it is good practise to name each source
630    file after the program unit it contains. It will make life a lot simpler
631    when using the <a href="#basic_interface">Automatic Fortran 9X interface
632    block</a> feature, which has already been discussed in the previous
633    section.
634      <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>
643      </ul>
644    </li>
645  </ol>
646
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>
691
692  <p>Apart from the usual dependency patterns described in the previous
693  sub-section, the automatic dependency scanner also recognises two special
694  directives when they are inserted into a source file:</p>
695
696  <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
700    needs to link with this external object in order to resolve all its
701    external references. It needs to be re-linked if the declared external
702    object (and its dependencies) has changed.</li>
703
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
706    executable file, which can be another script or a binary executable. The
707    current script can only function correctly if the declared executable is
708    found in the search path. This directive is useful to ensure that all
709    dependent executables are built or copied to the correct path.</li>
710  </ul>
711
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
727  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>
737cfg::type          ext
738cfg::version       1.0
739
740bld::exe_dep::foo.exe  foo::bar egg.o # line 4
741bld::exe_dep                          # line 5
742# ... some other declarations ...
743</pre>
744      </td>
745    </tr>
746  </table>
747
748  <p>Here is an explanation of what each line does:</p>
749
750  <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>
758  </ul>
759
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 
793  <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>
811cfg::type          ext
812cfg::version       1.0
813
814bld::excl_dep  USE::YourFortranMod             # line 4
815bld::excl_dep  INTERFACE::HerFortran.interface # line 5
816bld::excl_dep  INC::HisFortranInc.inc          # line 6
817bld::excl_dep  H::TheirHeader.h                # line 7
818bld::excl_dep  OBJ::ItsObject.o                # line 8
819
820# ... some other declarations ...
821</pre>
822      </td>
823    </tr>
824  </table>
825
826  <p>Here is an explanation of what each line does:</p>
827
828  <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>
866  </ul>
867
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>
873
874  <p>You can also exclude all dependency scan of a particular type. To do so,
875  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
879  <pre>
880bld::excl_dep  EXE
881</pre>
882
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
895  declarations:</p>
896
897  <pre>
898bld::blockdata::foo.exe  blkdata fbk
899</pre>
900
901  <p>If all your executables are dependent on "blkdata.o" and "fbk.o", you will
902  make the following declarations:</p>
903
904  <pre>
905bld::blockdata  blkdata fbk
906</pre>
907
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
924  <pre>
925bld::lib::foo::bar::egg  ham
926</pre>
927
928  <p>In addition to sub-package libraries, you can also build a global library
929  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
934  <pre>
935bld::lib  my-lib
936</pre>
937
938  <p>When a library archive is created successfully, the build system will
939  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>
948
949  <p>As most modern compilers can handle pre-processing, the build system
950  leaves pre-processing to the compiler by default. However, it is recognised
951  that there are code written with pre-processor directives that can alter the
952  argument list of procedures and/or their dependencies. If a source file
953  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>
967cfg::type          ext
968cfg::version       1.0
969
970bld::pp::gen       1                     # line 4
971bld::pp::var::foo  1                     # line 5
972
973bld::tool::cppkeys GOOD WEATHER FORECAST # line 7
974bld::tool::fppkeys FOO BAR EGG HAM       # line 8
975
976# ... some other declarations ...
977</pre>
978      </td>
979    </tr>
980  </table>
981
982  <p>Here is an explanation of what each line does:</p>
983
984  <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>
994  </ul>
995
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>
1001
1002  <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>
1018
1019  <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 
1026  <p>Following pre-processing, the system will use the pre-processed source
1027  file as if it is the original source file. The interface generator will
1028  generate the interface file using the pre-processed file, the dependency
1029  scanner will scan the pre-processed file for dependencies, and the compiler
1030  will compile the pre-processed source.</p>
1031
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>
1080
1081  <p>The build system only knows what to do with an input source file if it
1082  knows what type of file it is. The type of a source file is normally
1083  determined automatically using one of the following three methods (in
1084  order):</p>
1085
1086  <ol>
1087    <li>If the file is named with an extension, its extension will be matched
1088    against a set of registered file extensions. If a match is found, the file
1089    type will be set according to the register.</li>
1090
1091    <li>If a file does not have an extension or does not match with a
1092    registered extension, its name is compared with a set of pre-defined
1093    patterns. If a match is found, the file type will be set according to the
1094    file type associated with the pattern.</li>
1095
1096    <li>If the above two methods failed and if the file is a text file, the
1097    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
1100    according to the file type associated with the pattern.</li>
1101  </ol>
1102
1103  <p>In addition to the above, if a file is a Fortran or C source file, the
1104  system will attempt to open the source file to determine whether it contains
1105  a main program, module (Fortran only) or just standalone procedures. All
1106  these information will be used later by the build system to process the
1107  source file.</p>
1108
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 
1119  <p>The following is a list of default input file extensions and their
1120  associated types:</p>
1121
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>
1269
1270  <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>
1273
1274  <p>The following is a list of supported file name patterns and their
1275  associated types:</p>
1276
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>
1355
1356  <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>
1370cfg::type             ext
1371cfg::version          1.0
1372
1373bld::infile_ext::foo  CPP::INCLUDE                # line 4
1374bld::infile_ext::bar  FORTRAN::FORTRAN9X::INCLUDE # line 5
1375
1376# ... some other declarations ...
1377</pre>
1378      </td>
1379    </tr>
1380  </table>
1381
1382  <p>Here is an explanation of what each line does:</p>
1383
1384  <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>
1393  </ul>
1394
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>
1415cfg::type                   ext
1416cfg::version                1.0
1417
1418bld::outfile_ext::mk        .rule  # line 4
1419bld::outfile_ext::mod       .MOD   # line 5
1420bld::outfile_ext::interface .intfb # line 6
1421
1422# ... some other declarations ...
1423</pre>
1424      </td>
1425    </tr>
1426  </table>
1427
1428  <p>Here is an explanation of what each line does:</p>
1429
1430  <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>
1440  </ul>
1441
1442  <p>N.B. If you have made changes to the file type registers, whether it is
1443  for input files or output files, it is always worth re-building your code in
1444  full-build mode to avoid unexpected behaviour.</p>
1445
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>
1461
1462  <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:
1467      <pre>
1468inherit::target  1
1469</pre>
1470    </li>
1471
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
1507      <pre>
1508# Switch off inheritance of source directories in the "gen" sub-package
1509inherit::src::gen  0
1510</pre>
1511    </li>
1512
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>
1519  </ul>
1520
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>
1534cfg::type            ext
1535cfg::version         1.0
1536
1537use                  $HOME/example               # line 4
1538
1539dest::rootdir        $HOME/example9              # line 6
1540
1541bld::inherit::target 1                           # line 8
1542bld::target          ham.exe egg.exe             # line 9
1543
1544bld::tool::fflags    -O2 -w                      # line 11
1545bld::tool::cflags    -O2                         # line 12
1546
1547# ... and other declarations for repositories and source directories ...
1548</pre>
1549      </td>
1550    </tr>
1551  </table>
1552
1553  <p>Here is an explanation of what each line does:</p>
1554
1555  <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.
1564    Search paths of the build sub-directories will be set automatically. For
1565    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>
1578  </ul>
1579
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>
1611type::MyFortranProg.f90    FORTRAN::FORTRAN9X::SOURCE::PROGRAM # line 1
1612scan::MyFortranProg.f90    0                                   # line 2
1613intname::MyFortranProg.f90 myprog                              # line 3
1614target::MyFortranProg.f90  hello_world                         # line 4
1615
1616dep::MyFortranProg.f90     USE::YourFortranMod                 # line 6
1617dep::MyFortranProg.f90     INTERFACE::HerFortran.interface     # line 7
1618dep::MyFortranProg.f90     INC::HisFortranInc.inc              # line 8
1619dep::MyFortranProg.f90     H::TheirHeader.h                    # line 9
1620dep::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>
1675
1676  <p>While the usual targets to be built are the executables associated with
1677  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>
1694
1695  <p>The amount of diagnostic messages generated by the build system is
1696  normally set to a level suitable for normal everyday operation. This is the
1697  default diagnostic verbose level 1. If you want a minimum amount of
1698  diagnostic messages, you should set the verbose level to 0. If you want more
1699  diagnostic messages, you can set the verbose level to 2 or 3. You can modify
1700  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>
1704
1705  <p>The following is a list of diagnostic output at each verbose level:</p>
1706
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>
1819
1820  <p>The FCM build process can be summarised in five stages. Here is a summary
1821  of what is done in each stage:</p>
1822
1823  <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/"
1836    sub-directory of the build root.</li>
1837
1838    <li><strong>Generate dependency</strong>: the system scans source files of
1839    registered types for dependency information. For an incremental build, the
1840    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>
1849
1850    <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>
1970    </li>
1971  </ol>
1972
1973  <script type="text/javascript" src="maintain.js">
1974  </script>
1975</body>
1976</html>
Note: See TracBrowser for help on using the repository browser.