source: codes/icosagcm/trunk/tools/FCM/doc/user_guide/build.html @ 10

Last change on this file since 10 was 10, checked in by ymipsl, 12 years ago

dynamico tree creation

YM
File size: 77.6 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. Although you can declare different compiler flags, linker commands and
314  linker flags for different sub-packages, you cannot declare different
315  compilers for different sub-packages.</p>
316
317  <!--table class="pad" summary="note - TOOL declarations" border="1"
318  width="100%">
319    <tr>
320      <th>Note - TOOL declarations</th>
321    </tr>
322
323    <tr>
324      <td>The system does not stop you from making TOOL declarations that are
325      not supported, but it will only use the ones that are supported. For
326      example, you can define a compiler command for a sub-package, but it
327      will be ignored.</td>
328    </tr>
329  </table-->
330
331  <p>The following is an example setting in an extract configuration file
332  based on example 2:</p>
333
334  <table class="pad" summary="build_example3" border="1" width="100%">
335    <tr>
336      <th>Build configuration example 3 - compiler flags for different
337      sub-packages</th>
338    </tr>
339
340    <tr>
341      <td>
342        <pre>
343cfg::type              ext
344cfg::version           1.0
345
346dest::rootdir          $HOME/example
347
348bld::target            foo.exe bar.exe
349
350bld::tool::fc          ifc
351bld::tool::fflags      -O3    # line 9
352bld::tool::cc          gcc
353bld::tool::cflags      -O3
354bld::tool::ld          ifc
355bld::tool::ldflags     -L$(HOME)/lib -legg -lham
356
357bld::tool::fflags::ops -O1 -C # line 15
358bld::tool::fflags::gen -O2    # line 16
359
360# ... and other declarations for repositories and source directories ...
361</pre>
362      </td>
363    </tr>
364  </table>
365
366  <p>In the example above, line 15 alters the Fortran compiler flags for "ops",
367  so that all source files in "ops" will be compiled with optimisation level
368  1 and will have runtime error checking switched on. Line 16, alters the
369  Fortran compiler flags for "gen", so that all source files in "gen" will be
370  compiled with optimisation level 2. All other Fortran source files will use
371  the global setting declared at line 9, so they they will all be compiled
372  with optimisation level 3.</p>
373
374  <table class="pad" summary=
375  "note - changing compiler flags in incremental builds" border="1"
376  width="100%">
377    <tr>
378      <th>Note - changing compiler flags in incremental builds</th>
379    </tr>
380
381    <tr>
382      <td>
383        Suppose you have performed a successful build using the configuration
384        in example 3, and you have decided to change some of the compiler
385        flags, you can do so by altering the appropriate flags in the build
386        configuration file.  When you trigger an incremental build, the system
387        will detect changes in compiler flags automatically, and update only
388        the required targets. The following hierarchy is followed:
389
390        <ul>
391          <li>If the compiler flags for a particular source file change, only
392          that source file and any targets depending on that source file are
393          re-built.</li>
394
395          <li>If the compiler flags for a particular sub-package change, only
396          source files within that sub-package and any targets depending on
397          those source files are re-built.</li>
398
399          <li>If the global compiler flags change, all source files are
400          re-built.</li>
401
402          <li>If the compiler command changes, all source files are
403          re-built.</li>
404        </ul>
405
406        <!--p>The build system implements the above hierarchy using a "flags"
407        file system, which are dummy files created in the "flags/"
408        sub-directory of the build root. They are updated by the "touch"
409        command. The following dependencies are followed:</p>
410
411        <ul>
412          <li>Source files are dependent on its own "flags" file. E.g. the file
413          Ops_Switch in sub-package ":ops::code::OpsMod_Control" is dependent
414          on "FFLAGS__ops__code__OpsMod_Control__Ops_Switch.flags".</li>
415
416          <li>The "flags" file of a source file is dependent on the "flags" file
417          of its container sub-package. E.g. the above flags file is dependent
418          on "FFLAGS__ops__code__OpsMod_Control.flags".</li>
419
420          <li>The "flags" file of a sub-package is dependent on the "flags"
421          file of its container sub-package. E.g. the above is dependent on
422          "FFLAGS__ops__code.flags", which is dependent on
423          "FFLAGS__ops.flags".</li>
424
425          <li>The "flags" file of a top-level package is dependent on the
426          "flags" file of the global flags. E.g. "FFLAGS__ops.flags" is
427          dependent on "FFLAGS.flags".</li>
428
429          <li>The "flags" file of the global "flags" file is dependent on the
430          "flags" file of the compiler command. E.g. "FFLAGS.flags" is
431          dependent on "FC.flags".</li>
432        </ul>
433       
434        <p>The system records changes in declared tools using a cache file,
435        (called ".bld_tool", located at the ".cache/" sub-directory of the
436        built root). It is basically a list of "TOOL::" declarations for the
437        latest build.  When an incremental build is invoked, the list is
438        compared against the current set. If there are changes (modification,
439        addition and deletion) in any declarations, the timestamp of the
440        corresponding "flags" files will be updated. Files depending on the
441        updated "flags" file will then be considered out of date by
442        <em>make</em>, triggering a re-build of those files.</p-->
443      </td>
444    </tr>
445  </table>
446
447  <p>N.B. For a full list of build tools declarations, please see <a
448  href="annex_bld_cfg.html#tools-list">Annex: Declarations in FCM build
449  configuration file &gt; list of tools</a>.</p>
450
451  <h3><a name="basic_interface">Automatic Fortran 9X interface block</a></h3>
452
453  <p>For each Fortran 9X source file containing standalone subroutines and/or
454  functions, the system generates an interface file and sends it to the "inc/"
455  sub-directory of the build root. An interface file contains the interface
456  blocks for the subroutines and functions in the original source file. In an
457  incremental build, if you have modified a Fortran 9X source file, its
458  interface file will only be re-generated if the content of the interface has
459  changed.</p>
460 
461  <p>Consider a source file "foo.f90" containing a subroutine called "foo". In a
462  normal operation, the system writes the interface file to "foo.interface" in
463  the "inc/" sub-directory of the build root. By default, the root name of the
464  interface file is the same as that of the source file, and is case sensitive.
465  You can change this behaviour using a "TOOL::INTERFACE" declaration. E.g.:</p>
466
467  <pre>
468bld::tool::interface  program # The default is "file"
469</pre>
470
471  <p>In such case, the root name of the interface file will be named in lower
472  case after the first program unit in the file.</p>
473 
474  <p>The default extension for an interface file is ".interface". This can be
475  modified through the input and output file type register, which will be
476  discussed in a later section on <a href="#advanced_file-type">File
477  Type</a>.</p>
478 
479  <p>In most cases, we modify procedures without altering their calling
480  interfaces. Consider another source file "bar.f90" containing a subroutine
481  "bar". If "bar" calls "foo", it is good practice for "bar" to have an explicit
482  interface for "foo". This can be achieved if the subroutine "bar" has the
483  following within its declaration section:</p>
484
485  <pre>
486INCLUDE 'foo.interface'
487</pre>
488
489  <p>The source file "bar.f90" is now dependent on the interface file
490  "foo.interface". This can make incremental build very efficient, as changes
491  in the "foo.f90" file will not normally trigger the re-compilation of
492  "bar.f90", provided that the interface of the subroutine "foo" remains
493  unchanged. (However, the system is clever enough to know that it needs to
494  re-link any executables that are dependent on the object file for the
495  subroutine "bar".)</p>
496
497  <p>The default interface block generator is a piece of "plugged-in" Perl
498  code originally developed by the ECMWF. It has been modified at the Met
499  Office to work with FCM. Currently, the system can also work with the
500  interface generator <em>f90aib</em>, which is a freeware obtained from <a
501  href="http://www.ifremer.fr/ditigo/molagnon/fortran90/contenu.html">Fortran
502  90 texts and programs, assembled by Michel Olagnon</a> at the French
503  Research Institute for Exploitation of the Sea. To do so, you need to make a
504  declaration in the build configuration file using the label
505  "TOOL::GENINTERFACE". As for any other TOOL declarations, you can attach a
506  sub-package name to the label. The change will then apply only to source
507  files within that sub-package. If "TOOL::GENINTERFACE" is declared to have
508  the value "NONE", interface generation will be switched off. The following
509  are some examples:</p>
510
511  <table class="pad" summary="build_example4" border="1" width="100%">
512    <tr>
513      <th>Build configuration example 4 - Fortran 9X interface block
514      generator</th>
515    </tr>
516
517    <tr>
518      <td>
519        <pre>
520# This is an EXTRACT configuration file ...
521
522# ... some other declarations ...
523
524bld::tool::geninterface       f90aib # line 5
525bld::tool::geninterface::foo  ECMWF  # line 6
526bld::tool::geninterface::bar  none   # line 7
527
528# ... some other declarations ...
529</pre>
530      </td>
531    </tr>
532  </table>
533
534  <p>In line 5, the global interface generator is now set to <em>f90aib</em>.
535  In line 6, the interface generator for the package "foo" is set to the ECMWF
536  one. In line 7, by setting the interface generator for the package "bar" to
537  the "none" keyword, no interface file will be generated for source files
538  under the package "bar".</p>
539
540  <p>Switching off the interface block generator can be useful in many
541  circumstances. For example, if the interface block is already provided
542  manually within the source tree, or if the interface block is never used by
543  other program units, it is worth switching off the interface generator for
544  the source file to speed up the build process.</p>
545
546  <h3><a name="basic_dependency">Automatic dependency</a></h3>
547
548  <p>The build system has a built-in dependency scanner, which works out the
549  dependency relationship between source files, so that they can be built in
550  the correct order. The system scans all source files of known types for all
551  supported dependency patterns. Dependencies of source files in a sub-package
552  are written in a cache, which can be retrieved for incremental builds. (In
553  an incremental build, only changed source files need to be re-scanned for
554  dependency information. Dependency information for other files are retrieved
555  from the cache.) The dependency information is parsed to the <em>make</em>
556  rule generator, which writes the <em>Makefile</em> fragment for building the
557  source files in the sub-package. In an incremental build, a
558  <em>Makefile</em> fragment for a sub-package is only re-generated if a
559  source file in the sub-package has changed.</p>
560
561  <p>The <em>make</em> rule generator generates different <em>make</em> rules
562  for different dependency types. The following dependency patterns are
563  automatically detected by the current system:</p>
564
565  <ul>
566    <li>The [USE &lt;module&gt;] statement in a Fortran source file is the first
567    pattern. The statement has two implications: 1) The current file compiles
568    only if the module has been successfully compiled, and needs to be
569    re-compiled if the module has changed. 2) The executable depending on the
570    current file can only resolve all its externals by linking with the object
571    file of the compiled module. The executable needs to be re-linked if the
572    module and its dependencies has changed.</li>
573
574    <li>The [INCLUDE '&lt;name&gt;.interface'] statement in a Fortran source
575    file is the second pattern. (The default extension for an interface file is
576    ".interface". This can be modified through the input and output file type
577    register, which will be discussed in a later section on <a href=
578    "#advanced_file-type">File Type</a>.) It has two implications: 1) The
579    current file compiles only if the included interface file is in the INCLUDE
580    search path, and needs to be re-compiled if the interface file changes. 2)
581    The executable depending on the current file can only resolve all its
582    externals by linking with the object file of the source file that generates
583    the interface file. The executable needs to be re-linked if the source file
584    (and its dependencies) associated with the interface file has changed. It is
585    worth noting that for this dependency to work, the root &lt;name&gt; of the
586    interface file should match with that of the source file associated with the
587    interface file. (Please note that you can use pre-processor [#include
588    "&lt;name&gt;.interface] instead of Fortran INCLUDE, but it will not work
589    if you switch on the <a href="#advanced_pp">pre-processing</a> stage, which
590    will be discussed in a later section.)</li>
591
592    <li>The [INCLUDE '&lt;file&gt;'] statement (excluding the INCLUDE
593    interface file statement) in a Fortran source file is the third pattern.
594    It has two implications: 1) The current file compiles only if the included
595    file is in the INCLUDE search path, and needs to be re-compiled if the
596    include file changes. 2) The executable needs to be linked with any
597    objects the include file is dependent on. It needs to be re-linked if
598    these objects have changed.</li>
599
600    <li>The [#include '&lt;file&gt;'] statement in a Fortran/C source or header
601    file is the fourth pattern. It has similar implications as the Fortran
602    INCLUDE statement. However, they have to be handled differently because
603    "#include" statements are processed by the pre-processor, which may be
604    performed in a separate stage of the FCM build process. This will be
605    further discussed in a later sub-section on <a
606    href="#advanced_pp">Pre-processing</a>.</li>
607  </ul>
608
609  <p>If you want your code to be built automatically by the FCM build system,
610  you should also design your code to conform to the following rules:</p>
611
612  <ol>
613    <li>Single compilable program unit, (i.e. program, subroutine, function or
614    module), per file.</li>
615
616    <li>Unique name for each compilable program unit.</li>
617
618    <li>Always supply an interface for subroutines and functions, i.e.:
619      <ul>
620        <li>Put them in modules.</li>
621
622        <li>Put them in the CONTAINS section within the main program unit.</li>
623
624        <li>Use interface files.</li>
625      </ul>
626    </li>
627
628    <li>If interface files are used, it is good practise to name each source
629    file after the program unit it contains. It will make life a lot simpler
630    when using the <a href="#basic_interface">Automatic Fortran 9X interface
631    block</a> feature, which has already been discussed in the previous
632    section.
633      <ul>
634        <li>The problem is that, by default, the root name of the interface file
635            is the same as that of the source file rather than the program unit.
636            If they differ then the build system will create a dependency on the
637            wrong object file (since the object files are named according to the
638            program unit).</li>
639        <li>This problem can be avoided by changing the behaviour of the interface
640            file generator to use the name of the program unit instead (using a
641            "TOOL::INTERFACE" declaration).</li>
642      </ul>
643    </li>
644  </ol>
645
646  <table class="pad" summary=
647  "note - setting build targets" border="1" width="100%">
648    <tr>
649      <th>Note - setting build targets</th>
650    </tr>
651
652    <tr>
653      <td>
654        The <em>Makefile</em> (and its include fragments) generated by the
655        build system contains a list of targets that can be built. The build
656        system allows you to build (or perform the actions of) any targets that
657        are present in the generated <em>Makefile</em>. There are two ways to
658        specify the targets to be built. Firstly, you can use the TARGET
659        declarations in your build configuration file to specify the default
660        targets to be built.  These targets will be set as dependencies of the
661        "all" target in the generated <em>Makefile</em>, which is the default
662        target to be built when <em>make</em> is invoked by FCM. Alternatively,
663        you can use the "-t" option when you invoke the "fcm build" command. The
664        option takes an argument, which should be a colon ":" separated list of
665        targets to be built. When the "-t" option is set, FCM invokes
666        <em>make</em> to build these targets instead. (E.g. if we invoke the
667        build system with the command "fcm build -t foo.exe:bar.exe", it will
668        invoke <em>make</em> to build "foo.exe" and "bar.exe".)
669
670        <p>If you do not specify any explicit targets, the system will search
671        your source tree for main programs:</p>
672       
673        <ul>
674          <li>If there are main programs in your source tree, they will be set
675          as the default targets automatically.</li>
676
677          <li>Otherwise, the default is to build the top level library archive
678          containing objects compiled from the source files in the current
679          source tree. (For more information on building library archives,
680          please see the section on <a href="#advanced_library">Creating
681          library archives</a>.)</li>
682        </ul>
683      </td>
684    </tr>
685  </table>
686
687  <h2><a name="advanced">Advanced Features</a></h2>
688
689  <h3><a name="advanced_dependency">Further dependency features</a></h3>
690
691  <p>Apart from the usual dependency patterns described in the previous
692  sub-section, the automatic dependency scanner also recognises two special
693  directives when they are inserted into a source file:</p>
694
695  <ul>
696    <li>The directive [DEPENDS ON: &lt;object&gt;] in a comment line of a
697    Fortran/C source file: It states that the current file is dependent on the
698    declared external object. The executable depending on the current file
699    needs to link with this external object in order to resolve all its
700    external references. It needs to be re-linked if the declared external
701    object (and its dependencies) has changed.</li>
702
703    <li>The directive [CALLS: &lt;executable&gt;] in a comment line of a
704    script: It states that the current script is dependent on the declared
705    executable file, which can be another script or a binary executable. The
706    current script can only function correctly if the declared executable is
707    found in the search path. This directive is useful to ensure that all
708    dependent executables are built or copied to the correct path.</li>
709  </ul>
710
711  <p>There are situations when you need to bypass the automatic dependency
712  scanner. In such case, you may need to use a package configuration file. For
713  further information, please refer to the sub-section on <a href=
714  "#advanced_pckcfg">Using a package configuration file</a>.</p>
715
716  <p>Another way to specify external dependency is to use the EXE_DEP
717  declaration to declare extra dependencies. The declaration normally applies to
718  all main programs, but if the the form EXE_DEP::&lt;target&gt; is used, it
719  will only apply to &lt;target&gt;, (which must be the name of a main program
720  target). If the declaration is made without a value, the main programs will be
721  set to depend on all object files. Otherwise, the value can be supplied as a
722  space delimited list of items. Each item can be either the name of a
723  sub-package or an object target. For the former, the main programs will be set
724  to depend on all object files within the sub-package. For the latter, the main
725  programs will be set to depend on the object target. The following are some
726  examples:</p>
727
728  <table class="pad" summary="build_example5" border="1" width="100%">
729    <tr>
730      <th>Build configuration example 5 - extra executable dependency</th>
731    </tr>
732
733    <tr>
734      <td>
735        <pre>
736cfg::type          ext
737cfg::version       1.0
738
739bld::exe_dep::foo.exe  foo::bar egg.o # line 4
740bld::exe_dep                          # line 5
741# ... some other declarations ...
742</pre>
743      </td>
744    </tr>
745  </table>
746
747  <p>Here is an explanation of what each line does:</p>
748
749  <ul>
750    <li>line 4: this line declares the dependency on the sub-package "foo::bar"
751    and the object target "egg.o" for building the main program target
752    "foo.exe". The target "foo.exe" will now depends on all object files in the
753    "foo::bar" sub-package as well as the object target "egg.o".</li>
754
755    <li>line 5: this line declares that all other main program targets will
756    depend on all (non-program) object files in the build.</li>
757  </ul>
758
759  <table class="pad" summary="note - naming of object files" border="1"
760  width="100%">
761    <tr>
762      <th>Note - naming of object files</th>
763    </tr>
764
765    <tr>
766      <td>By default, object files are named with the suffix ".o". For a
767      Fortran source file, the build system uses the lower case name of the
768      first program unit within the file to name its object file. For example,
769      if the first program unit in the Fortran source file "foo.f90" is
770      "PROGRAM Bar", the object file will be "bar.o". For a C source file, the
771      build system uses the lower case root name of the source file to name
772      its object file. For example, a C source file called "egg.c" will have
773      its object file named "egg.o".
774     
775        <p>The reason for using lower case to name the object files is because
776        Fortran is a case insensitive language. Its symbols can either be in
777        lower or upper case. E.g. the SUBROUTINE "Foo" is the same as the
778        SUBROUTINE "foo". It can be rather confusing if the subroutines are
779        stored in different files. When they are compiled and archived into a
780        library, there will be a clash of namespace, as the Fortran compiler
781        thinks they are the same. However, this type of error does not normally
782        get reported. If "Foo" and "foo" are very different code, the user may
783        end up using the wrong subroutine, which may lead to a very long
784        debugging session. By naming all object files in lower case, this type
785        of situation can be avoided. If there is a clash in names due to the use
786        of upper/lower cases, it will be reported as warnings by <em>make</em>,
787        (as "duplicated targets" for building "foo.o").</p>
788      </td>
789    </tr>
790  </table>
791 
792  <p>It is realised that there are situations when an automatically detected
793  dependency should not be written into the <em>Makefile</em>. For example,
794  the dependency may be a standard module provided by the Fortran compiler,
795  and does not need to be built in the usual way. In such case, we need to
796  have a way to exclude this module during an automatic dependency scan.</p>
797
798  <p>The EXCL_DEP declaration can be used to do just that. The following
799  extract configuration contains some examples of the basic usage of the
800  EXCL_DEP declaration:</p>
801
802  <table class="pad" summary="build_example6" border="1" width="100%">
803    <tr>
804      <th>Build configuration example 6 - exclude dependency</th>
805    </tr>
806
807    <tr>
808      <td>
809        <pre>
810cfg::type          ext
811cfg::version       1.0
812
813bld::excl_dep  USE::YourFortranMod             # line 4
814bld::excl_dep  INTERFACE::HerFortran.interface # line 5
815bld::excl_dep  INC::HisFortranInc.inc          # line 6
816bld::excl_dep  H::TheirHeader.h                # line 7
817bld::excl_dep  OBJ::ItsObject.o                # line 8
818
819# ... some other declarations ...
820</pre>
821      </td>
822    </tr>
823  </table>
824
825  <p>Here is an explanation of what each line does:</p>
826
827  <ul>
828    <li>line 4: this line declares that the Fortran module "YourFortranMod"
829    should be excluded. The value of each EXCL_DEP declaration has two parts.
830    The first part is a label that is used to define the type of dependency to
831    be excluded. For a full list of these labels, please see the <a
832    href="annex_bld_cfg.html#dependency-types">dependency types table</a> in
833    the <a href="annex_bld_cfg.html">Annex:
834    Declarations in FCM build configuration file</a>. The label "USE"
835    denotes a Fortran module. The second part of the label is the dependency
836    itself. For instance, if a Fortran source file contains the line: "USE
837    YourFortranMod", the dependency scanner will ignore it.</li>
838
839    <li>line 5: this line declares that the include statement for the Fortran
840    9X interface file "HerFortran.interface" should be excluded. The label
841    "INTERFACE" denotes a Fortran INCLUDE statement for a Fortran 9X interface
842    block file. For example, if a Fortran source file contains the line:
843    "INCLUDE 'HerFortran.interface'", the dependency scanner will
844    ignore it.</li>
845
846    <li>line 6: this line declares that the include statement for
847    "HisFortranInc.inc" should be excluded. The label "INC" denotes a Fortran
848    INCLUDE statement other than an INCLUDE statement for an interface block
849    file. For example, if a Fortran source file contains the line:
850    "INCLUDE 'HisFortranInc.inc'", the dependency scanner will ignore
851    it.</li>
852
853    <li>line 7: this line declares that the header include statement
854    "TheirHeader.h" should be excluded. The label "H" denotes a pre-processing
855    #include statement. For example, if a source file contains the line:
856    "#include 'TheirHeader.h'", the dependency scanner will ignore
857    it.</li>
858
859    <li>line 8: this line declares that the external dependency for
860    "ItsObject.o" should be excluded. The label "OBJ" denotes a compiled
861    binary object. These dependencies are normally inserted into the source
862    files as special comments. For example, if a source file contains the line:
863    "! depends on: ItsObject.o", the dependency scanner will ignore
864    it.</li>
865  </ul>
866
867  <p>An EXCL_DEP declaration normally applies to all files in the build.
868  However, you can suffix it with the name of a sub-package, i.e.
869  EXCL_DEP::&lt;pcks&gt;. In such case, the declaration will only apply while
870  scanning for dependencies in the source files in the sub-package named
871  &lt;pcks&gt;.</p>
872
873  <p>You can also exclude all dependency scan of a particular type. To do so,
874  simply declare the type in the value. For example, if you do not want the
875  build system to scan for the [CALLS: &lt;executable&gt;] directive in the
876  comment lines of your scripts, you can make the following declaration:</p>
877
878  <pre>
879bld::excl_dep  EXE
880</pre>
881
882  <p>N.B. Currently, the build system is unable to detect changes in EXCL_DEP
883  declarations. Therefore, you will need to invoke the build system in full
884  build mode if you have changed these settings.</p>
885
886  <h3><a name="advanced_blockdata">Linking a Fortran executable with a BLOCKDATA
887  program unit</a></h3>
888
889  <p>If it is required to link Fortran executables with BLOCKDATA program units,
890  you must declare the executable targets and the objects containing the
891  BLOCKDATA program units using the BLOCKDATA::&lt;target&gt; declarations. For
892  example, if "foo.exe" is an executable target depending on the objects of the
893  BLOCKDATA program units "blkdata.o" and "fbk.o", you will make the following
894  declarations:</p>
895
896  <pre>
897bld::blockdata::foo.exe  blkdata fbk
898</pre>
899
900  <p>If all your executables are dependent on "blkdata.o" and "fbk.o", you will
901  make the following declarations:</p>
902
903  <pre>
904bld::blockdata  blkdata fbk
905</pre>
906
907  <h3><a name="advanced_library">Creating library archives</a></h3>
908
909  <p>If you are interested in building library archives, the build system allows
910  you to do it in a relatively simple way. For each sub-package in the source
911  tree, there is a target to build a library containing all the objects compiled
912  from the source files (that are not main programs) within the sub-package. If
913  the sub-package contains children sub-packages, the object files of the
914  children will also be included recursively. By default, the library archive is
915  named after the sub-package, in the format "lib&lt;pcks&gt;.a". (For example,
916  the library archive for the package "foo::bar::egg" will be named
917  "libfoo__bar__egg.a" by default.) If you do not like the default name for the
918  sub-package library, you can use the LIB::&lt;pcks&gt; declaration to rename
919  it, as long as the new name does not clash with other targets. For example, to
920  rename "libfoo__bar__egg.a" to "libham.a", you will make the following
921  declaration in your extract configuration file:</p>
922
923  <pre>
924bld::lib::foo::bar::egg  ham
925</pre>
926
927  <p>In addition to sub-package libraries, you can also build a global library
928  archive for the whole source tree. By default, the library is named
929  "libfcm_default.a", but you can rename it using the LIB declaration as above.
930  For example, to rename the library to "libmy-lib.a", you will make the
931  following declaration in your extract configuration file:</p>
932
933  <pre>
934bld::lib  my-lib
935</pre>
936
937  <p>When a library archive is created successfully, the build system will
938  automatically generate the relevant exclude dependency configurations in the
939  "etc/" sub-directory of the build root. You will be able to include these
940  configurations in subsequent builds that utilise the library. The root names
941  of the configuration files match those of the library archives that you can
942  create in the current build, but the extension "*.a" is replaced with "*.cfg".
943  For example, the exclude dependency configuration for "libmy-lib.a"
944  is "libmy-lib.cfg".</p>
945
946  <h3><a name="advanced_pp">Pre-processing</a></h3>
947
948  <p>As most modern compilers can handle pre-processing, the build system
949  leaves pre-processing to the compiler by default. However, it is recognised
950  that there are code written with pre-processor directives that can alter the
951  argument list of procedures and/or their dependencies. If a source file
952  requires pre-processing in such a way, we have to pre-process before running
953  the interface block generator and the dependency scanner. The PP declaration
954  can be used to switch on this pre-processing stage. The pre-processing stage
955  can be switched on globally or for individual sub-packages only. The
956  following is an example, using an extract configuration file:</p>
957
958  <table class="pad" summary="build_example7" border="1" width="100%">
959    <tr>
960      <th>Build configuration example 7 - pre-processing switch</th>
961    </tr>
962
963    <tr>
964      <td>
965        <pre>
966cfg::type          ext
967cfg::version       1.0
968
969bld::pp::gen       1                     # line 4
970bld::pp::var::foo  1                     # line 5
971
972bld::tool::cppkeys GOOD WEATHER FORECAST # line 7
973bld::tool::fppkeys FOO BAR EGG HAM       # line 8
974
975# ... some other declarations ...
976</pre>
977      </td>
978    </tr>
979  </table>
980
981  <p>Here is an explanation of what each line does:</p>
982
983  <ul>
984    <li>line 4 to 5: these switches on the pre-processing stage for all
985    sub-packages under "gen" and "var::foo".</li>
986
987    <li>line 7: this declares a list of pre-defined macros "GOOD", "WEATHER"
988    and "FORECAST" for pre-processing all C files.</li>
989
990    <li>line 8: this declares a list of pre-defined macros "FOO", "BAR",
991    "EGG" and "HAM" for pre-processing all Fortran files that require
992    processing.</li>
993  </ul>
994
995  <p>Source files requiring pre-processing may contain "#include" statements to
996  include header files. For including a local file, its name should be embedded
997  within a pair of quotes, i.e. 'file.h' or "file.h". If the header file is
998  embedded within a pair of "&lt;file.h&gt;" angle brackets, the system will
999  assume that the file can be found in a standard location.</p>
1000
1001  <p>The build system allows header files to be placed anywhere within the
1002  declared source tree. The system uses the dependency scanner, as described
1003  in the previous sub-section to scan for any header file dependencies. All
1004  source files requiring pre-processing and all header files are scanned. Header
1005  files that are required are copied to the "inc/" subdirectory of the build
1006  root, which is automatically added to the pre-processor search path via the
1007  "-I&lt;dir&gt;" option. The build system uses an internal logic similar to
1008  <em>make</em> to perform pre-processing. Header files are only copied to the
1009  "inc/" sub-directory if they are used in "#include" statements.</p>
1010 
1011  <p>Unlike <em>make</em>, which only uses the timestamp to determine whether an
1012  item is out of date, the internal logic of the build system does this by
1013  inspecting the content of the file as well. In an incremental build, the
1014  pre-processed file is only updated if its content has changed. This avoids
1015  unnecessary updates (and hence unnecessary re-compilation) in an incremental
1016  build if the changed section of the code does not affect the output file.</p>
1017
1018  <p>Pre-processed code generated during the pre-processing stage are sent to
1019  the "ppsrc/" sub-directory of the build root. It will have a relative path
1020  that reflects the name of the declared sub-package. The pre-processed source
1021  file will have the same root name as the original source file. For C files,
1022  the same extension ".c" will be used. For Fortran files, the case of the
1023  extension will normally be dropped, e.g. from ".F90" to ".f90".</p>
1024 
1025  <p>Following pre-processing, the system will use the pre-processed source
1026  file as if it is the original source file. The interface generator will
1027  generate the interface file using the pre-processed file, the dependency
1028  scanner will scan the pre-processed file for dependencies, and the compiler
1029  will compile the pre-processed source.</p>
1030
1031  <p>The TOOL::CPPKEYS and TOOL::FPPKEYS declarations are used to pre-define
1032  macros in the C and Fortran pre-processor respectively. This is implemented
1033  by the build system using the pre-processor "-D" option on each word in the
1034  list. The use of these declarations are not confined to the pre-process
1035  stage. If any source files requiring pre-processing are left to the compiler,
1036  the declarations will be used to set up the commands for compiling these
1037  source files.</p>
1038
1039  <p>The TOOL::CPPKEYS and TOOL::FPPKEYS declarations normally applies
1040  globally, but like any other TOOL declarations, they can be suffixed with
1041  sub-package names. In such cases, the declarations will apply only to the
1042  specified sub-packages.</p>
1043
1044  <table class="pad" summary="note - changing pre-processor flags" border="1"
1045  width="100%">
1046    <tr>
1047      <th>Note - changing pre-processor flags</th>
1048    </tr>
1049
1050    <tr>
1051      <td>
1052        As for compiler flags, the build system detects changes in
1053        pre-processor flags (TOOL::CPPFLAGS and TOOL::FPPFLAGS) and macro
1054        definitions (TOOL::CPPKEYS and TOOL::FPPKEYS). If the pre-processor
1055        flags or the macro definitions have changed in an incremental build,
1056        the system will re-do all the necessary pre-processing. The following
1057        hierarchy is followed:
1058
1059        <ul>
1060          <li>If the pre-processor flags or macro definitions for a particular
1061          source file change, only that source file will be pre-processed
1062          again.</li>
1063
1064          <li>If the pre-processor flags or macro definitions for a particular
1065          sub-package change, only source files within that sub-package will
1066          be pre-processed again.</li>
1067
1068          <li>If the global pre-processor flags or macro definitions change,
1069          all source files will be pre-processed again.</li>
1070
1071          <li>If the pre-processor command changes, all source files are
1072          pre-processed again.</li>
1073        </ul>
1074      </td>
1075    </tr>
1076  </table>
1077
1078  <h3><a name="advanced_file-type">File type</a></h3>
1079
1080  <p>The build system only knows what to do with an input source file if it
1081  knows what type of file it is. The type of a source file is normally
1082  determined automatically using one of the following three methods (in
1083  order):</p>
1084
1085  <ol>
1086    <li>If the file is named with an extension, its extension will be matched
1087    against a set of registered file extensions. If a match is found, the file
1088    type will be set according to the register.</li>
1089
1090    <li>If a file does not have an extension or does not match with a
1091    registered extension, its name is compared with a set of pre-defined
1092    patterns. If a match is found, the file type will be set according to the
1093    file type associated with the pattern.</li>
1094
1095    <li>If the above two methods failed and if the file is a text file, the
1096    system will attempt to read the first line of the file. If the first line
1097    begins with a "#!" pattern, the line will be compared with a set of
1098    pre-defined patterns. If a match is found, the file type will be set
1099    according to the file type associated with the pattern.</li>
1100  </ol>
1101
1102  <p>In addition to the above, if a file is a Fortran or C source file, the
1103  system will attempt to open the source file to determine whether it contains
1104  a main program, module (Fortran only) or just standalone procedures. All
1105  these information will be used later by the build system to process the
1106  source file.</p>
1107
1108  <p>The build system registers a file type with a set of type flags
1109  delimited by the double colons "::". For example, a Fortran 9X source file is
1110  registered as "FORTRAN::FORTRAN9X::SOURCE". (Please note that the
1111  order of the type flags in the list is insignificant. For example,
1112  "FORTRAN::SOURCE" is the same as "SOURCE::FORTRAN".) For a list of all the
1113  type flags used by the build system, please see the <a
1114  href="annex_bld_cfg.html#infile-ext-types">input file extension type
1115  flags table</a> in the <a href="annex_bld_cfg.html">
1116  Annex: Declarations in FCM build configuration file</a>.</p>
1117 
1118  <p>The following is a list of default input file extensions and their
1119  associated types:</p>
1120
1121  <table class="pad" summary="list of known file extensions" border="1">
1122    <tr>
1123      <th>Extensions</th>
1124
1125      <th>Type flags</th>
1126
1127      <th>Description</th>
1128    </tr>
1129
1130    <tr>
1131      <td class="mono">.f .for .ftn .f77</td>
1132
1133      <td class="mono">FORTRAN::SOURCE</td>
1134
1135      <td>Fortran 77 source file (assumed to be fixed format)</td>
1136    </tr>
1137
1138    <tr>
1139      <td class="mono">.f90 .f95</td>
1140
1141      <td class="mono">FORTRAN::FORTRAN9X::SOURCE</td>
1142
1143      <td>Fortran 9X source file (assumed to be free format)</td>
1144    </tr>
1145
1146    <tr>
1147      <td class="mono">.F .FOR .FTN .F77</td>
1148
1149      <td class="mono">FPP::SOURCE</td>
1150
1151      <td>Fortran 77 source file (assumed to be fixed format) that requires
1152      pre-processing</td>
1153    </tr>
1154
1155    <tr>
1156      <td class="mono">.F90 .F95</td>
1157
1158      <td class="mono">FPP::FPP9X::SOURCE</td>
1159
1160      <td>Fortran 9X source file (assumed to be free format) that requires
1161      pre-processing</td>
1162    </tr>
1163
1164    <tr>
1165      <td class="mono">.c</td>
1166
1167      <td class="mono">C::SOURCE</td>
1168
1169      <td>C source file</td>
1170    </tr>
1171
1172    <tr>
1173      <td class="mono">.h .h90</td>
1174
1175      <td class="mono">CPP::INCLUDE</td>
1176
1177      <td>Pre-processor "#include" header file</td>
1178    </tr>
1179
1180    <tr>
1181      <td class="mono">.o .obj</td>
1182
1183      <td class="mono">BINARY::OBJ</td>
1184
1185      <td>Compiled binary object</td>
1186    </tr>
1187
1188    <tr>
1189      <td class="mono">.exe</td>
1190
1191      <td class="mono">BINARY::EXE</td>
1192
1193      <td>Binary executable</td>
1194    </tr>
1195
1196    <tr>
1197      <td class="mono">.a</td>
1198
1199      <td class="mono">BINARY::LIB</td>
1200
1201      <td>Binary object library archive</td>
1202    </tr>
1203
1204    <tr>
1205      <td class="mono">.sh .ksh .bash .csh</td>
1206
1207      <td class="mono">SHELL::SCRIPT</td>
1208
1209      <td>Unix shell script</td>
1210    </tr>
1211
1212    <tr>
1213      <td class="mono">.pl .pm</td>
1214
1215      <td class="mono">PERL::SCRIPT</td>
1216
1217      <td>Perl script</td>
1218    </tr>
1219
1220    <tr>
1221      <td class="mono">.py</td>
1222
1223      <td class="mono">PYTHON::SCRIPT</td>
1224
1225      <td>Python script</td>
1226    </tr>
1227
1228    <tr>
1229      <td class="mono">.tcl</td>
1230
1231      <td class="mono">TCL::SCRIPT</td>
1232
1233      <td>Tcl/Tk script</td>
1234    </tr>
1235
1236    <tr>
1237      <td class="mono">.pro</td>
1238
1239      <td class="mono">PVWAVE::SCRIPT</td>
1240
1241      <td>PVWave program</td>
1242    </tr>
1243
1244    <tr>
1245      <td class="mono">.cfg</td>
1246
1247      <td class="mono">CFGFILE</td>
1248
1249      <td>FCM configuration file</td>
1250    </tr>
1251
1252    <tr>
1253      <td class="mono">.inc</td>
1254
1255      <td class="mono">FORTRAN::FORTRAN9X::INCLUDE</td>
1256
1257      <td>Fortran INCLUDE file</td>
1258    </tr>
1259
1260    <tr>
1261      <td class="mono">.interface</td>
1262
1263      <td class="mono">FORTRAN::FORTRAN9X::INCLUDE::INTERFACE</td>
1264
1265      <td>Fortran 9X INCLUDE interface block file</td>
1266    </tr>
1267  </table>
1268
1269  <p>N.B. The extension must be unique. For example, the system does not
1270  support the use of ".inc" files for both "#include" and Fortran
1271  "INCLUDE".</p>
1272
1273  <p>The following is a list of supported file name patterns and their
1274  associated types:</p>
1275
1276  <table class="pad" summary="list of known file name patterns" border="1">
1277    <tr>
1278      <th>Patterns</th>
1279
1280      <th>Type flags</th>
1281
1282      <th>Description</th>
1283    </tr>
1284
1285    <tr>
1286      <td class="mono">*Scr_* *Comp_* *IF_* *Suite_* *Interface_*</td>
1287
1288      <td class="mono">SHELL::SCRIPT</td>
1289
1290      <td>Unix shell script, GEN-based project naming conventions</td>
1291    </tr>
1292
1293    <tr>
1294      <td class="mono">*List_*</td>
1295
1296      <td class="mono">SHELL::SCRIPT::GENLIST</td>
1297
1298      <td>Unix shell script, GEN "list" file</td>
1299    </tr>
1300
1301    <tr>
1302      <td class="mono">*Sql_*</td>
1303
1304      <td class="mono">SCRIPT::SQL</td>
1305
1306      <td>SQL script, GEN-based project naming conventions</td>
1307    </tr>
1308  </table>
1309
1310  <p>The following is a list of supported "#!" line patterns and their
1311  associated types:</p>
1312
1313  <table class="pad" summary="list of known file name patterns" border="1">
1314    <tr>
1315      <th>Patterns</th>
1316
1317      <th>Type flags</th>
1318
1319      <th>Description</th>
1320    </tr>
1321
1322    <tr>
1323      <td class="mono">*sh* *ksh* *bash* *csh*</td>
1324
1325      <td class="mono">SHELL::SCRIPT</td>
1326
1327      <td>Unix shell script</td>
1328    </tr>
1329
1330    <tr>
1331      <td class="mono">*perl*</td>
1332
1333      <td class="mono">PERL::SCRIPT</td>
1334
1335      <td>Perl script</td>
1336    </tr>
1337
1338    <tr>
1339      <td class="mono">*python*</td>
1340
1341      <td class="mono">PYTHON::SCRIPT</td>
1342
1343      <td>Python script</td>
1344    </tr>
1345
1346    <tr>
1347      <td class="mono">*tclsh* *wish*</td>
1348
1349      <td class="mono">TCL::SCRIPT</td>
1350
1351      <td>Tcl/Tk script</td>
1352    </tr>
1353  </table>
1354
1355  <p>The build system allows you to add or modify the register for input file
1356  extensions and their associated type using the INFILE_EXT::&lt;ext&gt;
1357  declaration, where &lt;ext&gt; is a file name extension without the leading
1358  dot. For example, in an extract configuration file, you may have:</p>
1359
1360  <table class="pad" summary="build_example8" border="1" width="100%">
1361    <tr>
1362      <th>Build configuration example 8 - add/modify input file extension
1363      types</th>
1364    </tr>
1365
1366    <tr>
1367      <td>
1368        <pre>
1369cfg::type             ext
1370cfg::version          1.0
1371
1372bld::infile_ext::foo  CPP::INCLUDE                # line 4
1373bld::infile_ext::bar  FORTRAN::FORTRAN9X::INCLUDE # line 5
1374
1375# ... some other declarations ...
1376</pre>
1377      </td>
1378    </tr>
1379  </table>
1380
1381  <p>Here is an explanation of what each line does:</p>
1382
1383  <ul>
1384    <li>line 4: this line registers the extension ".foo" to be of type
1385    "CPP::INCLUDE". This means that any input files with ".foo"
1386    extension will be treated as if they are pre-processor header files.</li>
1387
1388    <li>line 5: this line registers the extension ".bar" to be of type
1389    "FORTRAN::FORTRAN9X::INCLUDE". This means that any input file
1390    with ".bar" extension will be treated as if they are Fortran 9X INCLUDE
1391    files.</li>
1392  </ul>
1393
1394  <p>The INFILE_EXT declarations deal with extensions of input files. There is
1395  also a OUTFILE_EXT::&lt;type&gt; declaration that deals with extensions of
1396  output files. The declaration is opposite that of INFILE_EXT. The file
1397  &lt;type&gt; is now declared with the label, and the extension is declared
1398  as the value. It is worth noting that OUTFILE_EXT declarations use very
1399  different syntax for &lt;type&gt;, and the declared extension must include
1400  the leading dot. For a list of output types used by the build system,
1401  please see the <a href="annex_bld_cfg.html#outfile-ext-types">output file
1402  extension types table</a> in the <a href="annex_bld_cfg.html">
1403  Annex: Declarations in FCM build configuration file</a>.
1404  An example is given below:</p>
1405
1406  <table class="pad" summary="build_example9" border="1" width="100%">
1407    <tr>
1408      <th>Build configuration example 9 - modify output file extensions</th>
1409    </tr>
1410
1411    <tr>
1412      <td>
1413        <pre>
1414cfg::type                   ext
1415cfg::version                1.0
1416
1417bld::outfile_ext::mk        .rule  # line 4
1418bld::outfile_ext::mod       .MOD   # line 5
1419bld::outfile_ext::interface .intfb # line 6
1420
1421# ... some other declarations ...
1422</pre>
1423      </td>
1424    </tr>
1425  </table>
1426
1427  <p>Here is an explanation of what each line does:</p>
1428
1429  <ul>
1430    <li>line 4: this line modifies the extension of output <em>Makefile</em>
1431    fragments, output of the dependency scanner, from the default ".mk" to
1432    ".rule".</li>
1433
1434    <li>line 5: this line modifies the extension of compiled Fortran 9X module
1435    information files from the default ".mod" to ".MOD".</li>
1436
1437    <li>line 6: this line modifies the extension of INCLUDE Fortran 9X
1438    interface block files from the default ".interface" to ".intfb".</li>
1439  </ul>
1440
1441  <p>N.B. If you have made changes to the file type registers, whether it is
1442  for input files or output files, it is always worth re-building your code in
1443  full-build mode to avoid unexpected behaviour.</p>
1444
1445  <h3><a name="advanced_incremental">Incremental build based on a pre-compiled
1446  build</a></h3>
1447
1448  <p>As you can perform incremental extractions against pre-extracted source
1449  code, you can perform incremental builds against pre-compiled builds. The
1450  very same USE statement can be used to declare a build, which the current
1451  build will depend on. The only difference is that the declared location must
1452  contain a valid build configuration file. In fact, if you use the extract
1453  system to obtain your build configuration file, any USE declarations in the
1454  extract configuration file will also be USE declarations in the output
1455  build configuration file.</p>
1456
1457  <p>By declaring a USE statement, the current build automatically inherits
1458  settings from the pre-compiled build. The following points are worth
1459  noting:</p>
1460
1461  <ul>
1462    <li>
1463      Build targets are not normally inherited. However, you can switch on
1464      inheritance of build targets using an INHERIT::TARGET declaration, such
1465      as:
1466      <pre>
1467inherit::target  1
1468</pre>
1469    </li>
1470
1471    <li> The build root directory and its sub-directories of the pre-compiled
1472    build are placed into the search paths. For example, if we have a
1473    pre-compiled build at "/path/to/pre/compiled", and it is used by an
1474    incremental build at "/path/to/incremental", the search path of executable
1475    files will become "/path/to/incremental/bin:/path/to/pre/compiled/bin", so
1476    that the "bin/" sub-directory of the incremental build is searched before
1477    the "bin/" sub-directory of the pre-compiled build. If two or more USE
1478    statements are declared, the USE statement declared last will have higher
1479    priority. For example, if the current build is "C", and it USEs build "A"
1480    before build "B", the search path will be "C:B:A".</li>
1481
1482    <li>
1483      Sub-package source directories are inherited by default. If a source
1484      directory is declared in the current build that has the same sub-package
1485      name as a source directory of the pre-compiled build, any source files in
1486      the source directory of the current build will override those in the
1487      source directory of the pre-compiled build. Any source files missing
1488      from the source directory of the current build will be taken from the
1489      source directory of the pre-compiled build.
1490
1491      <p>For example, if build "B" USEs build "A", and both of them have a
1492      sub-package called "basic::element". In build "A", the sub-package
1493      contains the source files "earth.f90", "wind.f90" and "water.f90". In
1494      build "B", the sub-package contains "earth.f90" and "fire.f90". When the
1495      system searches for source files, it will look for source files in "B"
1496      before "A". Therefore, the source file "earth.f90" in "B" will override
1497      that of "A", and the files used for the build will be "earth.f90" and
1498      "fire.f90" from "B" and "wind.f90" and "water.f90" from "A".</p>
1499     
1500      <p>You can switch off inheritance of source directories using an
1501      INHERIT::SRC declaration.  This declaration can be suffixed with the
1502      name of a sub-package. In such case, the declaration applies only to the
1503      inheritance of the sub-package. Otherwise, it applies to all source
1504      directories. For example:</p>
1505
1506      <pre>
1507# Switch off inheritance of source directories in the "gen" sub-package
1508inherit::src::gen  0
1509</pre>
1510    </li>
1511
1512    <li>All build tools are automatically inherited. If the same tool is
1513    declared in the current incremental build, it overrides the declaration in
1514    the pre-compiled build.</li>
1515
1516    <li>"PP", "EXCL_DEP", "INFILE_EXT" and "OUTFILE_EXT" declarations are
1517    inherited using a similar mechanism as build tool declarations.</li>
1518  </ul>
1519
1520  <p>As an example, suppose we have already performed an extract and build based
1521  on the configuration in example 2, we can set up an extract configuration
1522  file as follows:</p>
1523
1524  <table class="pad" summary="build_example10" border="1" width="100%">
1525    <tr>
1526      <th>Build configuration example 10 - "USE" a pre-compiled
1527      build</th>
1528    </tr>
1529
1530    <tr>
1531      <td>
1532        <pre>
1533cfg::type            ext
1534cfg::version         1.0
1535
1536use                  $HOME/example               # line 4
1537
1538dest::rootdir        $HOME/example9              # line 6
1539
1540bld::inherit::target 1                           # line 8
1541bld::target          ham.exe egg.exe             # line 9
1542
1543bld::tool::fflags    -O2 -w                      # line 11
1544bld::tool::cflags    -O2                         # line 12
1545
1546# ... and other declarations for repositories and source directories ...
1547</pre>
1548      </td>
1549    </tr>
1550  </table>
1551
1552  <p>Here is an explanation of what each line does:</p>
1553
1554  <ul>
1555    <li>line 4: this line declares a previous extraction at
1556    "$HOME/example" which the current extraction will be based on. The
1557    same line will be written to the output build configuration file at
1558    "$HOME/example9/cfg/bld.cfg". The subsequent build will then be
1559    based on the build at "$HOME/example".</li>
1560
1561    <li>line 6: this declares the destination root directory of the current
1562    extraction, which will become the root directory of the current build.
1563    Search paths of the build sub-directories will be set automatically. For
1564    example, the search path for executable files created by the current build
1565    will be "$HOME/example9/bin:$HOME/example/bin".</li>
1566
1567    <li>line 8: this line switches on inheritance of build targets. The build
1568    targets in example 1, i.e. "foo.exe" and "bar.exe" will be built as part
1569    of the current build.</li>
1570
1571    <li>line 9: this declares two new build targets "ham.exe" and "egg.exe" to
1572    be added to the inherited ones. The default build targets of the current
1573    build will now be "foo.exe", "bar.exe", "ham.exe" and "egg.exe".</li>
1574
1575    <li>line 11-12: these lines modify options used by the Fortran and the C
1576    compilers, overriding those inherited from example 1.</li>
1577  </ul>
1578
1579  <h3><a name="advanced_pckcfg">Using a package configuration file</a></h3>
1580
1581  <p>It is recognised that the build system needs to be able to work with code
1582  that is not designed to work with the automatic dependency scanner. There are
1583  various techniques which can be used to achieve this, some of which are
1584  already described. However, it should be noted that these techniques are
1585  simply designed to allow code to be successfully built. They will not
1586  necessarily result in a good environment for developing such code, since for
1587  example, dependencies need to be manually maintained by the developer.</p>
1588
1589  <p>The final technique is the package configuration file. The package
1590  configuration file is a special source file to inform the build system about
1591  any additional information of the source files in the package. It must be a
1592  file called "@PACKAGE.cfg" in a source directory. For a full list of available
1593  declarations in the package configuration file, please refer to the <a
1594  href="annex_pck_cfg.html">Annex: Declarations in FCM build package
1595  configuration file</a>.</p>
1596
1597  <p>The following is an example of how a package configuration file can be
1598  used to provide additional information to the build system for a source
1599  file:</p>
1600
1601  <table class="pad" summary="package_example1" border="1" width="100%">
1602    <tr>
1603      <th>Package configuration example 1 - dependency information for a
1604      source file</th>
1605    </tr>
1606
1607    <tr>
1608      <td>
1609        <pre>
1610type::MyFortranProg.f90    FORTRAN::FORTRAN9X::SOURCE::PROGRAM # line 1
1611scan::MyFortranProg.f90    0                                   # line 2
1612intname::MyFortranProg.f90 myprog                              # line 3
1613target::MyFortranProg.f90  hello_world                         # line 4
1614
1615dep::MyFortranProg.f90     USE::YourFortranMod                 # line 6
1616dep::MyFortranProg.f90     INTERFACE::HerFortran.interface     # line 7
1617dep::MyFortranProg.f90     INC::HisFortranInc.inc              # line 8
1618dep::MyFortranProg.f90     H::TheirHeader.h                    # line 9
1619dep::MyFortranProg.f90     OBJ::ItsObject.o                    # line 10
1620
1621# ... some other declarations ...
1622</pre>
1623      </td>
1624    </tr>
1625  </table>
1626
1627  <p>Here is an explanation of what each line does:</p>
1628
1629  <ul>
1630    <li>line 1: this declares a source file "MyFortranProg.f90" in the package
1631    of type "FORTRAN::FORTRAN9X::SOURCE::PROGRAM", i.e. a Fortran 9X source
1632    file containing a main program. The list of type flags used in the value
1633    is the same list of type flags used in the INFILE_EXT declaration of a
1634    build configuration file. For a list of  these flags, please see the <a
1635    href="annex_bld_cfg.html#infile-ext-types">Input file extension type flags
1636    table</a> in the <a href="annex_bld_cfg.html">
1637    Annex: Declarations in FCM build configuration file</a>.</li>
1638
1639    <li>line 2: this declaration switches off (0) automatic dependency scan for
1640    this source file. If this switch is not declared, it is automatically set
1641    to on (1) for a source file. If the switch is on, the dependency scanner
1642    will scan the source file for further dependencies. Otherwise, dependency
1643    information for this source file will only be read from this configuration
1644    file.</li>
1645
1646    <li>line 3: this declares the internal name of the source file to be
1647    "myprog". If this is not set and the dependency scanner is switched on,
1648    the internal name of the source file will be taken from the first program
1649    unit of the source file. The resulting object file will be named after
1650    the internal name, plus the ".o" extension. If internal name is not set
1651    and cannot be determined automatically, the default is to use the root
1652    name of the source file to name the object file.</li>
1653
1654    <li>line 4: this declares the executable target name of a main program.
1655    This declaration is only used when the source file contains a main
1656    program. If the target name is not set, the name of the executable will be
1657    named after the root name of the source file plus the ".exe" extension. In
1658    the above example, the executable will be named "hello_world".</li>
1659
1660    <li>line 6-10: these lines declare the dependencies of the source file.
1661    The syntax of the values are exactly the same as those used in the
1662    EXCL_DEP declarations in the build configuration file. For a list of these
1663    flags, please see the <a
1664    href="annex_bld_cfg.html#dependency-types">dependency types table</a> in
1665    the <a href="annex_bld_cfg.html">Annex:
1666    Declarations in FCM build configuration file</a>. In the example,
1667    the source file is dependent on a Fortran module called "YourFortranMod",
1668    a Fortran INCLUDE interface block file called "HerFortran.interface", a
1669    Fortran INCLUDE file called "HistFortran.inc, a pre-processor header file
1670    called "TheirHeader.h", and an object file called "ItsObject.o".</li>
1671  </ul>
1672
1673  <h3><a name="advanced_data">Building data files</a></h3>
1674
1675  <p>While the usual targets to be built are the executables associated with
1676  source files containing main programs, libraries or scripts, the build system
1677  also allows you to build "data" files. All files with no registered type are
1678  considered to be "data" files.  For each sub-package, there is an automatic
1679  target for copying all "data" files to the "etc/" sub-directory of the build
1680  root. The name of the target has the form "&lt;pcks&gt;.etc", where
1681  &lt;pcks&gt; is the name of the sub-package (with package names delimited by
1682  the double underscore "__"). For example, the target name for sub-package
1683  "foo::bar" is "foo__bar.etc". This target is particularly useful for copying,
1684  say, all namelists in a sub-package to the "etc/" sub-directory of the build
1685  root.</p>
1686
1687  <p>At the end of a successful build, if the "etc/" sub-directory is not empty,
1688  the "fcm_env.ksh" script will export the environment variable FCM_ETCDIR to
1689  point to the "etc/" sub-directory. You should be able to use this environment
1690  variable to locate your data files.</p>
1691
1692  <h2><a name="verbose">Diagnostic verbose level</a></h2>
1693
1694  <p>The amount of diagnostic messages generated by the build system is
1695  normally set to a level suitable for normal everyday operation. This is the
1696  default diagnostic verbose level 1. If you want a minimum amount of
1697  diagnostic messages, you should set the verbose level to 0. If you want more
1698  diagnostic messages, you can set the verbose level to 2 or 3. You can modify
1699  the verbose level in two ways. The first way is to set the environment
1700  variable FCM_VERBOSE to the desired verbose level. The second way is to
1701  invoke the build system with the "-v &lt;level&gt;" option. (If set, the
1702  command line option overrides the environment variable.)</p>
1703
1704  <p>The following is a list of diagnostic output at each verbose level:</p>
1705
1706  <table class="pad" summary="List of diagnostic verbose output" border="1">
1707    <tr>
1708      <th>Verbose level</th>
1709
1710      <th>Possible output</th>
1711    </tr>
1712
1713    <tr>
1714      <th>0</th>
1715
1716      <td>
1717        <ul>
1718          <li>Report the time taken at the end of each stage of the build
1719          process.</li>
1720
1721          <li>Run the <em>make</em> command in silent mode.</li>
1722        </ul>
1723      </td>
1724    </tr>
1725
1726    <tr>
1727      <th>1</th>
1728
1729      <td>
1730        <ul>
1731          <li>Everything at verbose level 0.</li>
1732
1733          <li>Report the name of the build configuration file.</li>
1734
1735          <li>Report date/time at the beginning of each stage of the build
1736          process.</li>
1737
1738          <li>Report removed directories.</li>
1739
1740          <li>Report number of pre-processed files.</li>
1741
1742          <li>Report number of generated F9X interface files.</li>
1743
1744          <li>Report number of sub-packages that have source files scanned
1745          for dependencies.</li>
1746
1747          <li>Report number of generated/updated sub-package <em>make</em>
1748          rule fragment files.</li>
1749
1750          <li>Report name of updated <em>Makefile</em>.</li>
1751
1752          <li>Print compiler/linker commands.</li>
1753
1754          <li>Report total time.</li>
1755        </ul>
1756      </td>
1757    </tr>
1758
1759    <tr>
1760      <th>2</th>
1761
1762      <td>
1763        <ul>
1764          <li>Everything at verbose level 1.</li>
1765
1766          <li>For incremental build in archive mode, report the commands used
1767          to extract the archives.</li>
1768
1769          <li>Report creation and removal of directories.</li>
1770
1771          <li>Report pre-processor commands.</li>
1772
1773          <li>Report number of files scanned for dependency in each
1774          sub-package.</li>
1775
1776          <li>Report names of generated/updated sub-package <em>make</em> rule
1777          fragment files.</li>
1778
1779          <li>Print compiler/linker commands with timestamps.</li>
1780
1781          <li>Print usage of the runtime environment set up script.</li>
1782        </ul>
1783      </td>
1784    </tr>
1785
1786    <tr>
1787      <th>3</th>
1788
1789      <td>
1790        <ul>
1791          <li>Everything at verbose level 2.</li>
1792
1793          <li>Report update of dummy files.</li>
1794
1795          <li>Report all shell commands.</li>
1796
1797          <li>Report pre-processor commands with timestamps.</li>
1798
1799          <li>If F9X interface is generated by <em>f90aib</em>, print commands
1800          with timestamps.</li>
1801
1802          <li>If F9X interface is generated by ECMWF code, report start
1803          date/time and time taken to generate each interface file.</li>
1804
1805          <li>Report start date/time and time taken of dependency scan for each
1806          source file.</li>
1807
1808          <li>Run <em>make</em> on normal mode (as opposed to silent mode).</li>
1809
1810          <li>Report start date/time and time taken of <em>make</em>
1811          commands.</li>
1812        </ul>
1813      </td>
1814    </tr>
1815  </table>
1816
1817  <h2><a name="overview">Overview of the build process</a></h2>
1818
1819  <p>The FCM build process can be summarised in five stages. Here is a summary
1820  of what is done in each stage:</p>
1821
1822  <ol>
1823    <li><strong>Setup</strong>: in this first stage, the build system reads
1824    and processes the configuration file. The source sub-directory is searched
1825    recursively for source directories. For full builds, it ensures that the
1826    sub-directories created by the build system are removed. For inherited
1827    (i.e. pre-compiled) builds, it sets up the search paths for the
1828    sub-directories, inherits the targets, source directories, etc. For
1829    incremental builds, the system also works out whether the current list of
1830    build tools have changed.</li>
1831
1832    <li><strong>Pre-process</strong>: if any files in any source directories
1833    require pre-processing, they will be pre-processed at this stage. The
1834    resulting pre-processed source files will be sent to the "ppsrc/"
1835    sub-directory of the build root.</li>
1836
1837    <li><strong>Generate dependency</strong>: the system scans source files of
1838    registered types for dependency information. For an incremental build, the
1839    information is only updated if a source file is changed. The system then
1840    uses the information to write a <em>Makefile</em> for the main build. The
1841    <em>Makefile</em> and any of its included fragments are generated in the
1842    "bld/" sub-directory of the build root.</li>
1843
1844    <li><strong>Generate interface</strong>: if there are Fortran 9X source
1845    files with standalone subroutines and functions, the build system
1846    generates interface blocks for them. The result of which will be written
1847    to the interface files in the "inc/" sub-directory of the build root.</li>
1848
1849    <li>
1850      <strong>Make</strong>: the system invokes <em>make</em> on the
1851      <em>Makefile</em> generated in the previous stage to perform the main
1852      build. Following a build, the "root" directory of the build may contain
1853      the following sub-directories (empty ones are removed automatically at the
1854      end of the build process):
1855
1856      <table summary="list of build sub-directories" border="1" width="100%">
1857        <tr>
1858          <th>Sub-directory</th>
1859
1860          <th>Contents</th>
1861
1862          <th>Note</th>
1863        </tr>
1864
1865        <tr>
1866          <th>.cache/</th>
1867
1868          <td>&lt;cache files&gt;</td>
1869
1870          <td>used internally by FCM</td>
1871        </tr>
1872
1873        <tr>
1874          <th>bin/</th>
1875
1876          <td>&lt;executable binaries and scripts&gt;</td>
1877
1878          <td>-</td>
1879        </tr>
1880
1881        <tr>
1882          <th>bld/</th>
1883
1884          <td>Makefile and &lt;Makefile include files&gt;</td>
1885
1886          <td>-</td>
1887        </tr>
1888
1889        <tr>
1890          <th>cfg/</th>
1891
1892          <td>bld.cfg</td>
1893
1894          <td>this directory is not changed by the build system</td>
1895        </tr>
1896
1897        <tr>
1898          <th>done/</th>
1899
1900          <td>&lt;dummy "done" files&gt;</td>
1901
1902          <td>used internally by the Makefile generated by FCM</td>
1903        </tr>
1904
1905        <tr>
1906          <th>etc/</th>
1907
1908          <td>&lt;miscellaneous data files&gt;</td>
1909
1910          <td>-</td>
1911        </tr>
1912
1913        <tr>
1914          <th>flags/</th>
1915
1916          <td>&lt;dummy "flags" files&gt;</td>
1917
1918          <td>used internally by the Makefile generated by FCM</td>
1919        </tr>
1920
1921        <tr>
1922          <th>inc/</th>
1923
1924          <td>&lt;include files&gt;</td>
1925
1926          <td>such as *.h, *.inc, *.interface and *.mod files</td>
1927        </tr>
1928
1929        <tr>
1930          <th>lib/</th>
1931
1932          <td>&lt;object library archives&gt;</td>
1933
1934          <td>-</td>
1935        </tr>
1936
1937        <tr>
1938          <th>obj/</th>
1939
1940          <td>&lt;compiled object files&gt;</td>
1941
1942          <td>-</td>
1943        </tr>
1944
1945        <tr>
1946          <th>ppsrc/</th>
1947
1948          <td>&lt;source directories with pre-processed files&gt;</td>
1949
1950          <td>-</td>
1951        </tr>
1952
1953
1954        <tr>
1955          <th>src/</th>
1956
1957          <td>&lt;source directories&gt;</td>
1958
1959          <td>this directory is not changed by the build system</td>
1960        </tr>
1961        <tr>
1962          <th>tmp/</th>
1963
1964          <td>&lt;temporary objects and binaries&gt;</td>
1965
1966          <td>files generated by the compiler/linker may be left here</td>
1967        </tr>
1968      </table>
1969    </li>
1970  </ol>
1971
1972  <script type="text/javascript" src="maintain.js">
1973  </script>
1974</body>
1975</html>
Note: See TracBrowser for help on using the repository browser.