source: LMDZ6/branches/Amaury_dev/tools/fcm/doc/user_guide/build.html @ 5129

Last change on this file since 5129 was 5129, checked in by abarral, 5 months ago

Re-add removed by mistake fcm
File size: 72.8 KB
Line 
1<!DOCTYPE html>
2<html>
3<head>
4  <title>FCM: User Guide: Annex: The FCM 1 Build System</title>
5  <meta name="author" content="FCM team" />
6  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
7  <link rel="icon" href="../etc/fcm-icon.png" type="image/png" />
8  <link rel="shortcut icon" href="../etc/fcm-icon.png" type="image/png" />
9  <link href="../etc/bootstrap/css/bootstrap.min.css" rel="stylesheet" media="screen" />
10  <link href="../etc/fcm.css" rel="stylesheet" media="screen" />
11</head>
12<body>
13  <div class="navbar navbar-inverse">
14    <div class="container-fluid">
15      <div class="navbar-header">
16        <a class="navbar-brand" href=".."><span class="fcm-version">FCM</span></a>
17      </div>
18      <div class="collapse navbar-collapse">
19        <ul class="nav navbar-nav">
20          <li><a href="../installation/">Installation</a></li>
21
22          <li><a class="active" href="#">User Guide</a></li>
23        </ul>
24      </div>
25    </div>
26  </div>
27
28  <div class="page-header">
29    <div class="fcm-page-content pull-right well well-sm"></div>
30    <h1>FCM: User Guide: Annex: The FCM 1 Build System</h1>
31  </div>
32
33  <div class="container">
34  <div class="row">
35  <div class="col-md-12">
36
37  <h2 id="introduction">Introduction</h2>
38
39  <p><em>The FCM 1 build system is deprecated. The documentation for the current
40  build system can be found at <a href="make.html">FCM Make</a>.</em></p>
41
42  <p>The build system analyses the directory tree containing a set of source
43  code, processes the configuration, and invokes <code>make</code> to
44  compile/build the source code into the project executables. In this chapter,
45  we shall use many examples to explain how to use the build system. At the end
46  of this chapter, you should be able to use the build system, either by
47  defining the build configuration file directly or by using the extract system
48  to generate a suitable build configuration file.</p>
49
50  <h2 id="command">The Build Command</h2>
51
52  <p>To invoke the build system, simply issue the command:</p>
53  <pre>
54fcm build
55</pre>
56
57  <p>By default, the build system searches for a build configuration file
58  <samp>bld.cfg</samp> in <samp>$PWD</samp> and then <samp>$PWD/cfg</samp>. If
59  a build configuration file is not found in these directories, the command
60  fails with an error. If a build configuration file is found, the system will
61  use the configuration specified in the file to perform the build. If you use
62  the extract system to extract your source tree, a build configuration should
63  be written for you automatically at the <samp>cfg/</samp> sub-directory of
64  the destination root directory.</p>
65
66  <p>If the root directory of the build does not exist, the system performs a
67  new full build at this directory. If a previous build already exists at this
68  directory, the system performs an incremental build. If a full (fresh) build
69  is required for whatever reason, you can invoke the build system using the
70  <code>-f</code> option, (i.e. the command becomes <code>fcm build -f</code>).
71  If you simply want to remove all the items generated by a previous build in
72  the destination, you can invoke the build system using the
73  <code>--clean</code> option.</p>
74
75  <p>The build system uses GNU <code>make</code> to perform the majority of the
76  build. GNU <code>make</code> has a <code>-j jobs</code> option to specify the
77  number of <var>jobs</var> to run simultaneously. Invoking the build system
78  with the same option triggers this option when the build system invokes the
79  <code>make</code> command. The argument to the option <var>jobs</var> must be
80  an integer. The default is <samp>1</samp>. For example, the command <code>fcm
81  build -j 4</code> will allow <code>make</code> to perform 4 jobs
82  simultaneously.</p>
83
84  <p>For further information on the build command, please see <a href=
85  "command_ref.html#fcm-build">FCM Command Reference &gt; fcm build</a>.</p>
86
87  <h2 id="basic">Basic Features</h2>
88
89  <p>The build configuration file is the user interface of the build system. It
90  is a line based text file. You can create your own build configuration file
91  or you can use the extract system to create one for you. For a complete set
92  of build configuration file declarations, please refer to the <a href=
93  "annex_bld_cfg.html">Annex: Declarations in FCM build configuration
94  file</a>.</p>
95
96  <h3 id="basic_build">Basic build configuration</h3>
97
98  <p>Suppose we have a directory at <samp>$HOME/example</samp>. Its
99  sub-directory at <samp>$HOME/example/src</samp> contains a source tree to be
100  built. You may want to have a build configuration file
101  <samp>$HOME/example/cfg/bld.cfg</samp>, which may contain:</p>
102  <pre id="example_1">
103# Example 1
104# ----------------------------------------------------------------------
105cfg::type     bld                           # line 1
106cfg::version  1.0                           # line 2
107
108dest          $HOME/example                 # line 4
109
110target        foo.exe bar.exe               # line 6
111
112tool::fc      ifort                         # line 8
113tool::fflags  -O3                           # line 9
114tool::cc      gcc                           # line 10
115tool::cflags  -O3                           # line 11
116
117tool::ldflags -O3 -L$(HOME)/lib -legg -lham # line 13
118</pre>
119
120  <p>Here is an explanation of what each line does:</p>
121
122  <ul>
123    <li><dfn>line 1</dfn>: the label <code>CFG::TYPE</code> declares the type
124    of the configuration file. The value <samp>bld</samp> tells the system that
125    it is a build configuration file.</li>
126
127    <li><dfn>line 2</dfn>: the label <code>CFG::VERSION</code> declares the
128    version of the build configuration file. The current default is
129    <samp>1.0</samp>. Although it is not currently used, if we have to change
130    the format of the configuration file at a later stage, we shall be able to
131    use this number to determine whether we are reading a file with an older
132    format or one with a newer format.</li>
133
134    <li><dfn>line 4</dfn>: the label <code>DEST</code> declares the root
135    directory of the current build.</li>
136
137    <li><dfn>line 6</dfn>: the label <code>TARGET</code> declares a list of
138    <em>default</em> targets. The default targets of the current build will be
139    <samp>foo.exe</samp> and <samp>bar.exe</samp>.</li>
140
141    <li><dfn>line 8</dfn>: the label <code>TOOL::FC</code> declares the Fortran
142    compiler command.</li>
143
144    <li><dfn>line 9</dfn>: the label <code>TOOL::FFLAGS</code> declares the
145    options to be used when invoking the Fortran compiler command.</li>
146
147    <li><dfn>line 10</dfn>: the label <code>TOOL::CC</code> declares the C
148    compiler command.</li>
149
150    <li><dfn>line 11</dfn>: the label <code>TOOL::CFLAGS</code> declares the
151    options to be used when invoking the C compiler command.</li>
152
153    <li><dfn>line 13</dfn>: the label <code>TOOL::LDFLAGS</code> declares the
154    options to be used when invoking the linker command.</li>
155  </ul>
156
157  <p>When we invoke the build system, it reads the above configuration file. It
158  will go through various internal processes, such as dependency generations,
159  to obtain the required information to prepare the <samp>Makefile</samp> of
160  the build. (All of which will be described in later sections.) The
161  <samp>Makefile</samp> of the build will be placed at
162  <samp>$HOME/example/bld</samp>. The system will then invoke <code>make</code>
163  to build the targets specified in line 6, i.e. <samp>foo.exe</samp> and
164  <samp>bar.exe</samp> using the build tools specified between line 8 to line
165  13. On a successful build, the target executables will be sent to
166  <samp>$HOME/example/bin/</samp>. The build system also creates a shell script
167  called <samp>fcm_env.sh</samp> in <samp>$HOME/example/</samp>. If you source
168  the shell script, it will export your <var>PATH</var> environment variable to
169  search the <samp>$HOME/example/bin/</samp> directory for executables.</p>
170
171  <p>N.B. You may have noticed that the <code>-c</code> (compile to object file
172  only) option is missing from the compiler flags declarations. This is because
173  the option is inserted automatically by the build system, unless it is
174  already declared.</p>
175
176  <p>N.B. You can declare the linker using <code>TOOL::LD</code>. If it is not
177  specified, the default is to use the compiler command for the source file
178  containing the main program.</p>
179
180  <dl>
181    <dt>Note - declaration of source files for build</dt>
182
183    <dd>
184      <p>Source files do not have to reside in the <samp>src/</samp>
185      sub-directory of the build root directory. They can be anywhere, but you
186      will have to declare them using the label <code>SRC::&lt;pcks&gt;</code>,
187      where <code>&lt;pcks&gt;</code> is the sub-package name in which the
188      source belongs. If a directory is specified then the build system
189      automatically searches for all source files in this directory. E.g.</p>
190      <pre>
191# Declare a source in the sub-package "foo/bar"
192src::foo/bar  $HOME/foo/bar
193</pre>
194
195      <p>By default, the build system searches the <samp>src/</samp>
196      sub-directory of the build root directory for source files. If all source
197      files are already declared explicitly, you can switch off the automatic
198      directory search by setting the <code>SEARCH_SRC</code> flag to false.
199      E.g.</p>
200      <pre>
201search_src  false
202</pre>
203
204      <p>As mentioned in the previous chapter, the name of a sub-package
205      &lt;pcks&gt; provides a unique namespace for a file. The name of a
206      sub-package is a list of words delimited by a slash <code>/</code>. (The
207      system uses the double colons <code>::</code> and the double underscores
208      <code>__</code> internally. Please avoid using <code>::</code> and
209      <code>__</code> for naming your files and directories.)</p>
210
211      <p>Currently, the build system only supports non-space characters in the
212      package name, as the space character is used as a delimiter between the
213      declaration label and its value. If there are spaces in the path name to
214      a file or directory, you should explicity re-define the package name of
215      that path to a package name with no space using the above method.
216      However, we recommend that only non-space characters are used for naming
217      directories and files to make life simple.</p>
218
219      <p>In the build system, the sub-package name also provides an
220      <em>inheritance</em> relationship for sub-packages. For instance, we may
221      have a sub-package called <samp>foo/bar/egg</samp>, which belongs to the
222      sub-package <samp>foo/bar</samp>, which belongs to the package
223      <samp>foo</samp>.</p>
224
225      <ul>
226        <li>If we declare a global build tool, it applies to all packages.</li>
227
228        <li>If we declare a build tool for <samp>foo</samp>, it applies also to
229        the sub-package <samp>foo/bar</samp> and <samp>foo/bar/egg</samp>.</li>
230
231        <li>If we declare a build tool for <samp>foo/bar</samp>, it applies
232        also to <samp>foo/bar/egg</samp>, but not to other sub-packages in
233        <samp>foo</samp>.</li>
234      </ul>
235    </dd>
236  </dl>
237
238  <h3 id="basic_extract">Build configuration via the extract system</h3>
239
240  <p>As mentioned earlier, you can obtain a build configuration file through
241  the extract system. The following example is what you may have in your
242  extract configuration in order to obtain a similar configuration as <a href=
243  "#example_1">example 1</a>:</p>
244  <pre id="example_2">
245# Example 2
246# ----------------------------------------------------------------------
247cfg::type          ext                           # line 1
248cfg::version       1.0                           # line 2
249
250dest               $HOME/example                 # line 4
251
252bld::target        foo.exe bar.exe               # line 6
253
254bld::tool::fc      ifort                         # line 8
255bld::tool::fflags  -O3                           # line 9
256bld::tool::cc      gcc                           # line 10
257bld::tool::cflags  -O3                           # line 11
258
259bld::tool::ldflags -O3 -L$(HOME)/lib -legg -lham # line 13
260
261# ... and other declarations for source locations ...
262</pre>
263
264  <p>It is easy to note the similarities and differences between <a href=
265  "#example_1">example 1</a> and <a href="#example_2">example 2</a>. <a href=
266  "#example_2">Example 2</a> is an extract configuration file. It extracts to a
267  destination root directory that will become the root directory of the build.
268  Line 6 to line 13 are the same declarations, except that they are now
269  prefixed with <code>BLD::</code>. In an extract configuration file, any lines
270  prefixed with <code>BLD::</code> means that they are build configuration
271  setting. These lines are ignored by the extract system but are parsed down to
272  the output build configuration file, with the <code>BLD::</code> prefix
273  removed. (Note: the <code>BLD::</code> prefix is optional for declarations in
274  a build configuration file.)</p>
275
276  <p>N.B. If you use the extract system to mirror an extract to an alternate
277  location, the extract system will assume that the root directory of the
278  alternate destination is the root directory of the build, and that the build
279  will be carried out in that destination.</p>
280
281  <h3 id="basic_exename">Naming of executables</h3>
282
283  <p>If a source file called <samp>foo.f90</samp> contains a main program, the
284  default behaviour of the system is to name its executable
285  <samp>foo.exe</samp>. The root name of the executable is the same as the
286  original file name, but its file extension is replaced with
287  <samp>.exe</samp>. The output extension can be altered by re-registering the
288  extension for output EXE files. How this can be done will be discussed later
289  in the sub-section <a href="#advanced_file-type">File Type</a>.</p>
290
291  <p>If you need to alter the full name of the executable, you can use the
292  <code>EXE_NAME::</code> declaration. For example, the declaration:</p>
293  <pre>
294bld::exe_name::foo  bar
295</pre>
296
297  <p>will rename the executable of <samp>foo.f90</samp> from
298  <samp>foo.exe</samp> to <samp>bar</samp>.</p>
299
300  <p>Note: the declaration label is <code>bld::exe_name::foo</code> (not
301  <code>bld::exe_name::foo.exe</code>) and the executable will be named
302  <samp>bar</samp> (not <samp>bar.exe</samp>).</p>
303
304  <h3 id="basic_flags">Setting the compiler flags</h3>
305
306  <p>As discussed in the first example, the compiler commands and their flags
307  can be set via the <code>TOOL::</code> declarations. A simple
308  <code>TOOL::FFLAGS</code> declaration, for example, alters the compiler
309  options for compiling all Fortran source files in the build. If you need to
310  alter the compiler options only for the source files in a particular
311  sub-package, it is possible to do so by adding the sub-package name to the
312  declaration label. For example, the declaration label
313  <code>TOOL::FFLAGS::foo/bar</code> will ensure that the declaration only
314  applies to the code in the sub-package <samp>foo/bar</samp>. You can even
315  make declarations down to the individual source file level. For example, the
316  declaration label <code>TOOL::FFLAGS::foo/bar/egg.f90</code> will ensure that
317  the declaration applies only for the file <samp>foo/bar/egg.f90</samp>.</p>
318
319  <p>N.B. Although the prefix <code>TOOL::</code> and the tool names are
320  case-insensitive, sub-package names are case sensitive in the declarations.
321  Internally, tool names are turned into uppercase, and the sub-package
322  delimiters are changed from the slash <code>/</code> (or double colons
323  <code>::</code>) to the double underscores <code>__</code>. When the system
324  generates the <samp>Makefile</samp> for the build, each <code>TOOL</code>
325  declaration will be exported as an environment variable. For example, the
326  declaration <code>tool::fflags/foo/bar</code> will be exported as
327  <samp>FFLAGS__foo__bar</samp>.</p>
328
329  <p>N.B. <code>TOOL</code> declarations for sub-packages are only accepted by
330  the system when it is sensible to do so. For example, it allows you to
331  declare different compiler flags, linker commands and linker flags for
332  different sub-packages, but it does not accept different compilers for
333  different sub-packages. If you attempt to make a <code>TOOL</code>
334  declaration for a sub-package that does not exist, the build system will exit
335  with an error.</p>
336
337  <p>The following is an example setting in an extract configuration file based
338  on <a href="#example_2">example 2</a>:</p>
339  <pre id="example_3">
340# Example 3
341# ----------------------------------------------------------------------
342cfg::type              ext
343cfg::version           1.0
344
345dest                   $HOME/example
346
347bld::target            foo.exe bar.exe
348
349bld::tool::fc          ifort
350bld::tool::fflags      -O3    # line 9
351bld::tool::cc          gcc
352bld::tool::cflags      -O3
353
354bld::tool::ldflags     -L$(HOME)/lib -legg -lham
355
356bld::tool::fflags::ops -O1 -C # line 15
357bld::tool::fflags::gen -O2    # line 16
358
359# ... and other declarations for repositories and source directories ...
360</pre>
361
362  <p>In the example above, line 15 alters the Fortran compiler flags for
363  <samp>ops</samp>, so that all source files in <samp>ops</samp> will be
364  compiled with optimisation level 1 and will have runtime error checking
365  switched on. Line 16, alters the Fortran compiler flags for <samp>gen</samp>,
366  so that all source files in <samp>gen</samp> will be compiled with
367  optimisation level 2. All other Fortran source files will use the global
368  setting declared at line 9, so they they will all be compiled with
369  optimisation level 3.</p>
370
371  <dl>
372    <dt>Note - changing compiler flags in incremental builds</dt>
373
374    <dd>
375      <p>Suppose you have performed a successful build using the configuration
376      in <a href="#example_3">example 3</a>, and you have decided to change
377      some of the compiler flags, you can do so by altering the appropriate
378      flags in the build configuration file. When you trigger an incremental
379      build, the system will detect changes in compiler flags automatically,
380      and update only the required targets. The following hierarchy is
381      followed:</p>
382
383      <ul>
384        <li>If the compiler flags for a particular source file change, only
385        that source file and any targets depending on that source file are
386        re-built.</li>
387
388        <li>If the compiler flags for a container package change, only source
389        files within that container package and any targets depending on those
390        source files are re-built.</li>
391
392        <li>If the global compiler flags change, all source files are
393        re-built.</li>
394
395        <li>If the compiler command changes, all source files are
396        re-built.</li>
397      </ul>
398    </dd>
399  </dl>
400
401  <p>N.B. For a full list of build tools declarations, please see <a href=
402  "annex_bld_cfg.html#tools-list">Annex: Declarations in FCM build
403  configuration file &gt; list of tools</a>.</p>
404
405  <h3 id="basic_interface">Automatic Fortran 9X interface block</h3>
406
407  <p>For each Fortran 9X source file containing standalone subroutines and/or
408  functions, the system generates an interface file and sends it to the
409  <samp>inc/</samp> sub-directory of the build root. An interface file contains
410  the interface blocks for the subroutines and functions in the original source
411  file. In an incremental build, if you have modified a Fortran 9X source file,
412  its interface file will only be re-generated if the content of the interface
413  has changed.</p>
414
415  <p>Consider a source file <samp>foo.f90</samp> containing a subroutine called
416  <samp>foo</samp>. In a normal operation, the system writes the interface file
417  to <samp>foo.interface</samp> in the <samp>inc/</samp> sub-directory of the
418  build root. By default, the root name of the interface file is the same as
419  that of the source file, and is case sensitive. You can change this behaviour
420  using a <code>TOOL::INTERFACE</code> declaration. E.g.:</p>
421  <pre>
422bld::tool::interface  program # The default is "file"
423</pre>
424
425  <p>In such case, the root name of the interface file will be named in lower
426  case after the first program unit in the file.</p>
427
428  <p>The default extension for an interface file is <samp>.interface</samp>.
429  This can be modified through the input and output file type register, which
430  will be discussed in a later section on <a href="#advanced_file-type">File
431  Type</a>.</p>
432
433  <p>In most cases, we modify procedures without altering their calling
434  interfaces. Consider another source file <samp>bar.f90</samp> containing a
435  subroutine <samp>bar</samp>. If <samp>bar</samp> calls <samp>foo</samp>, it
436  is good practice for <samp>bar</samp> to have an explicit interface for
437  <samp>foo</samp>. This can be achieved if the subroutine <samp>bar</samp> has
438  the following within its declaration section:</p>
439  <pre>
440INCLUDE 'foo.interface'
441</pre>
442
443  <p>The source file <samp>bar.f90</samp> is now dependent on the interface
444  file <samp>foo.interface</samp>. This can make incremental build very
445  efficient, as changes in the <samp>foo.f90</samp> file will not normally
446  trigger the re-compilation of <samp>bar.f90</samp>, provided that the
447  interface of the <code>subroutine foo</code> remains unchanged. (However, the
448  system is clever enough to know that it needs to re-link any executables that
449  are dependent on the object file for the <code>subroutine bar</code>.)</p>
450
451  <p>By default, the system uses its own internal logic to extract the calling
452  interfaces of top level subroutines and functions in a Fortran source file to
453  generate an interface block. However, the system can also work with the
454  interface generator <code>f90aib</code>, which is a freeware obtained from
455  <a href=
456  "http://www.ifremer.fr/ditigo/molagnon/fortran90/contenu.html">Fortran 90
457  texts and programs, assembled by Michel Olagnon</a> at the French Research
458  Institute for Exploitation of the Sea. To do so, you need to make a
459  declaration in the build configuration file using the label
460  <code>TOOL::GENINTERFACE</code>. As for any other <code>TOOL</code>
461  declarations, you can attach a sub-package name to the label. The change will
462  then apply only to source files within that sub-package. If
463  <code>TOOL::GENINTERFACE</code> is declared to have the value
464  <code>NONE</code>, interface generation will be switched off. The following
465  are some examples:</p>
466  <pre id="example_4">
467# Example 4
468# ----------------------------------------------------------------------
469# This is an EXTRACT configuration file ...
470
471# ... some other declarations ...
472
473bld::tool::geninterface       f90aib # line 5
474bld::tool::geninterface::bar  none   # line 6
475
476# ... some other declarations ...
477</pre>
478
479  <p>In line 5, the global interface generator is now set to
480  <code>f90aib</code>. In line 6, by setting the interface generator for the
481  package <samp>bar</samp> to the <code>none</code> keyword, no interface file
482  will be generated for source files under the package <samp>bar</samp>.</p>
483
484  <p>Switching off the interface block generator can be useful in many
485  circumstances. For example, if the interface block is already provided
486  manually within the source tree, or if the interface block is never used by
487  other program units, it is worth switching off the interface generator for
488  the source file to speed up the build process.</p>
489
490  <h3 id="basic_dependency">Automatic dependency</h3>
491
492  <p>The build system has a built-in dependency scanner, which works out the
493  dependency relationship between source files, so that they can be built in
494  the correct order. The system scans all source files of known types for all
495  supported dependency patterns. Dependencies of source files in a sub-package
496  are written in a cache, which can be retrieved for incremental builds. (In an
497  incremental build, only changed source files need to be re-scanned for
498  dependency information. Dependency information for other files are retrieved
499  from the cache.) The dependency information is passed to the
500  <code>make</code> rule generator, which writes the <samp>Makefile</samp>.</p>
501
502  <p>The <code>make</code> rule generator generates different <code>make</code>
503  rules for different dependency types. The following dependency patterns are
504  automatically detected by the current system:</p>
505
506  <ul>
507    <li>The <code>USE &lt;module&gt;</code> statement in a Fortran source file
508    is the first pattern. The statement has two implications: 1) The current
509    file compiles only if the module has been successfully compiled, and needs
510    to be re-compiled if the module has changed. 2) The executable depending on
511    the current file can only resolve all its externals by linking with the
512    object file of the compiled module. The executable needs to be re-linked if
513    the module and its dependencies has changed.</li>
514
515    <li>The <code>INCLUDE '&lt;name&gt;.interface'</code> statement in a
516    Fortran source file is the second pattern. (The default extension for an
517    interface file is <samp>.interface</samp>. This can be modified through the
518    input and output file type register, which will be discussed in a later
519    section on <a href="#advanced_file-type">File Type</a>.) It has two
520    implications: 1) The current file compiles only if the included interface
521    file is in the INCLUDE search path, and needs to be re-compiled if the
522    interface file changes. 2) The executable depending on the current file can
523    only resolve all its externals by linking with the object file of the
524    source file that generates the interface file. The executable needs to be
525    re-linked if the source file (and its dependencies) associated with the
526    interface file has changed. It is worth noting that for this dependency to
527    work, the root &lt;name&gt; of the interface file should match with that of
528    the source file associated with the interface file. (Please note that you
529    can use pre-processor [#include "&lt;name&gt;.interface] instead of Fortran
530    INCLUDE, but it will not work if you switch on the <a href=
531    "#advanced_pp">pre-processing</a> stage, which will be discussed in a later
532    section.)</li>
533
534    <li>The <code>INCLUDE '&lt;file&gt;'</code> statement (excluding the
535    INCLUDE interface file statement) in a Fortran source file is the third
536    pattern. It has two implications: 1) The current file compiles only if the
537    included file is in the INCLUDE search path, and needs to be re-compiled if
538    the include file changes. 2) The executable needs to be linked with any
539    objects the include file is dependent on. It needs to be re-linked if these
540    objects have changed.</li>
541
542    <li>The <code>#include '&lt;file&gt;'</code> statement in a Fortran/C
543    source or header file is the fourth pattern. It has similar implications as
544    the Fortran INCLUDE statement. However, they have to be handled differently
545    because <code>#include</code> statements are processed by the
546    pre-processor, which may be performed in a separate stage of the FCM build
547    process. This will be further discussed in a later sub-section on <a href=
548    "#advanced_pp">Pre-processing</a>.</li>
549  </ul>
550
551  <p>If you want your code to be built automatically by the FCM build system,
552  you should also design your code to conform to the following rules:</p>
553
554  <ol>
555    <li>Single compilable program unit, (i.e. program, subroutine, function or
556    module), per file.</li>
557
558    <li>Unique name for each compilable program unit.</li>
559
560    <li>Always supply an interface for subroutines and functions, i.e.:
561
562      <ul>
563        <li>Put them in modules.</li>
564
565        <li>Put them in the CONTAINS section within the main program unit.</li>
566
567        <li>Use interface files.</li>
568      </ul>
569    </li>
570
571    <li>If interface files are used, it is good practice to name each source
572    file after the program unit it contains. It will make life a lot simpler
573    when using the <a href="#basic_interface">Automatic Fortran 9X interface
574    block</a> feature, which has already been discussed in the previous
575    section.
576
577      <ul>
578        <li>The problem is that, by default, the root name of the interface
579        file is the same as that of the source file rather than the program
580        unit. If they differ then the build system will create a dependency on
581        the wrong object file (since the object files are named according to
582        the program unit).</li>
583
584        <li>This problem can be avoided by changing the behaviour of the
585        interface file generator to use the name of the program unit instead
586        (using a <code>TOOL::INTERFACE</code> declaration).</li>
587      </ul>
588    </li>
589  </ol>
590
591  <dl>
592    <dt>Note - setting build targets</dt>
593
594    <dd>
595      <p>The <samp>Makefile</samp> generated by the build system contains a
596      list of targets that can be built. The build system allows you to build
597      (or perform the actions of) any targets that are present in the generated
598      <samp>Makefile</samp>. There are two ways to specify the targets to be
599      built.</p>
600
601      <p>Firstly, you can use the <code>TARGET</code> declarations in your
602      build configuration file to specify the default targets to be built.
603      These targets will be set as dependencies of the <samp>all</samp> target
604      in the generated <samp>Makefile</samp>, which is the default target to be
605      built when <code>make</code> is invoked by FCM. It is worth noting that
606      <code>TARGET</code> declarations are cumulative. A later declaration does
607      not override an earlier one - it simply adds more targets to the
608      list.</p>
609
610      <p>Alternatively, you can use the <code>-t</code> option when you invoke
611      the <code>fcm build</code> command. The option takes an argument, which
612      should be a colon <code>:</code> separated list of targets to be built.
613      When the <code>-t</code> option is set, FCM invokes <code>make</code> to
614      build these targets instead. (E.g. if we invoke the build system with the
615      command <code>fcm build -t foo.exe:bar.exe</code>, it will invoke
616      <code>make</code> to build <samp>foo.exe</samp> and
617      <samp>bar.exe</samp>.)</p>
618
619      <p>If you do not specify any explicit targets, the system will search
620      your source tree for main programs:</p>
621
622      <ul>
623        <li>If there are main programs in your source tree, they will be set as
624        the default targets automatically.</li>
625
626        <li>Otherwise, the default is to build the top level library archive
627        containing objects compiled from the source files in the current source
628        tree. (For more information on building library archives, please see
629        the section on <a href="#advanced_library">Creating library
630        archives</a>.)</li>
631      </ul>
632    </dd>
633  </dl>
634
635  <h2 id="advanced">Advanced Features</h2>
636
637  <h3 id="advanced_dependency">Further dependency features</h3>
638
639  <p>Apart from the usual dependency patterns described in the previous
640  sub-section, the automatic dependency scanner also recognises two special
641  directives when they are inserted into a source file:</p>
642
643  <ul>
644    <li>The directive <code>DEPENDS ON: &lt;object&gt;</code> in a comment line
645    of a Fortran/C source file: It states that the current file is dependent on
646    the declared external object. The executable depending on the current file
647    needs to link with this external object in order to resolve all its
648    external references. It needs to be re-linked if the declared external
649    object (and its dependencies) has changed.</li>
650
651    <li>The directive <code>CALLS: &lt;executable&gt;</code> in a comment line
652    of a script: It states that the current script is dependent on the declared
653    executable file, which can be another script or a binary executable. The
654    current script can only function correctly if the declared executable is
655    found in the search path. This directive is useful to ensure that all
656    dependent executables are built or copied to the correct path.</li>
657  </ul>
658
659  <p>Another way to specify external dependency is to use the
660  <code>EXE_DEP</code> declaration to declare extra dependencies. The
661  declaration normally applies to all main programs, but if the form
662  <code>EXE_DEP::&lt;target&gt;</code> is used, it will only apply to
663  &lt;target&gt;, (which must be the name of a main program target). If the
664  declaration is made without a value, the main programs will be set to depend
665  on all object files. Otherwise, the value can be supplied as a space
666  delimited list of items. Each item can be either the name of a sub-package or
667  an object target. For the former, the main programs will be set to depend on
668  all object files within the sub-package. For the latter, the main programs
669  will be set to depend on the object target. The following are some
670  examples:</p>
671  <pre id="example_5">
672# Example 5
673# ----------------------------------------------------------------------
674cfg::type          ext
675cfg::version       1.0
676
677bld::exe_dep::foo.exe  foo/bar egg.o # line 4
678bld::exe_dep                         # line 5
679# ... some other declarations ...
680</pre>
681
682  <p>Here is an explanation of what each line does:</p>
683
684  <ul>
685    <li><dfn>line 4</dfn>: this line declares the dependency on the sub-package
686    <samp>foo/bar</samp> and the object target <samp>egg.o</samp> for building
687    the main program target <samp>foo.exe</samp>. The target
688    <samp>foo.exe</samp> will now depends on all object files in the
689    <samp>foo/bar</samp> sub-package as well as the object target
690    <samp>egg.o</samp>.</li>
691
692    <li><dfn>line 5</dfn>: this line declares that all other main program
693    targets will depend on all (non-program) object files in the build.</li>
694  </ul>
695
696  <dl>
697    <dt>Note - naming of object files</dt>
698
699    <dd>
700      <p>By default, object files are named with the suffix <samp>.o</samp>.
701      For a Fortran source file, the build system uses the lower case name of
702      the first program unit within the file to name its object file. For
703      example, if the first program unit in the Fortran source file
704      <samp>foo.f90</samp> is <code>PROGRAM Bar</code>, the object file will be
705      <samp>bar.o</samp>. For a C source file, the build system uses the lower
706      case root name of the source file to name its object file. For example, a
707      C source file called <samp>egg.c</samp> will have its object file named
708      <samp>egg.o</samp>.</p>
709
710      <p>The reason for using lower case to name the object files is because
711      Fortran is a case insensitive language. Its symbols can either be in
712      lower or upper case. E.g. the <code>SUBROUTINE Foo</code> is the same as
713      the <code>SUBROUTINE foo</code>. It can be rather confusing if the
714      subroutines are stored in different files. When they are compiled and
715      archived into a library, there will be a clash of namespace, as the
716      Fortran compiler thinks they are the same. However, this type of error
717      does not normally get reported. If <samp>Foo</samp> and <samp>foo</samp>
718      are very different code, the user may end up using the wrong subroutine,
719      which may lead to a very long debugging session. By naming all object
720      files in lower case, this type of situation can be avoided. If there is a
721      clash in names due to the use of upper/lower cases, it will be reported
722      as warnings by the build system, (as <em>duplicated targets</em> for
723      building <samp>foo.o</samp>).</p>
724    </dd>
725  </dl>
726
727  <p>It is realised that there are situations when an automatically detected
728  dependency should not be written into the <samp>Makefile</samp>. For example,
729  the dependency may be a standard module provided by the Fortran compiler, and
730  does not need to be built in the usual way. In such case, we need to have a
731  way to exclude this module during an automatic dependency scan.</p>
732
733  <p>The <code>EXCL_DEP</code> declaration can be used to do just that. The
734  following extract configuration contains some examples of the basic usage of
735  the <code>EXCL_DEP</code> declaration:</p>
736  <pre id="example_6">
737# Example 6
738# ----------------------------------------------------------------------
739cfg::type          ext
740cfg::version       1.0
741
742bld::excl_dep  USE::YourFortranMod             # line 4
743bld::excl_dep  INTERFACE::HerFortran.interface # line 5
744bld::excl_dep  INC::HisFortranInc.inc          # line 6
745bld::excl_dep  H::TheirHeader.h                # line 7
746bld::excl_dep  OBJ::ItsObject.o                # line 8
747
748# ... some other declarations ...
749</pre>
750
751  <p>Here is an explanation of what each line does:</p>
752
753  <ul>
754    <li><dfn>line 4</dfn>: this line declares that the Fortran module
755    <samp>YourFortranMod</samp> should be excluded. The value of each
756    <code>EXCL_DEP</code> declaration has two parts. The first part is a label
757    that is used to define the type of dependency to be excluded. For a full
758    list of these labels, please see the <a href=
759    "annex_bld_cfg.html#dependency-types">dependency types table</a> in the
760    <a href="annex_bld_cfg.html">Annex: Declarations in FCM build configuration
761    file</a>. The label <code>USE</code> denotes a Fortran module. The second
762    part of the label is the dependency itself. For instance, if a Fortran
763    source file contains the line: <code>USE YourFortranMod</code>, the
764    dependency scanner will ignore it.</li>
765
766    <li><dfn>line 5</dfn>: this line declares that the include statement for
767    the Fortran 9X interface file <samp>HerFortran.interface</samp> should be
768    excluded. The label <code>INTERFACE</code> denotes a Fortran INCLUDE
769    statement for a Fortran 9X interface block file. For example, if a Fortran
770    source file contains the line: <code>INCLUDE 'HerFortran.interface'</code>,
771    the dependency scanner will ignore it.</li>
772
773    <li><dfn>line 6</dfn>: this line declares that the include statement for
774    <samp>HisFortranInc.inc</samp> should be excluded. The label
775    <code>INC</code> denotes a Fortran INCLUDE statement other than an INCLUDE
776    statement for an interface block file. For example, if a Fortran source
777    file contains the line: <code>INCLUDE 'HisFortranInc.inc'</code>, the
778    dependency scanner will ignore it.</li>
779
780    <li><dfn>line 7</dfn>: this line declares that the header include statement
781    <samp>TheirHeader.h</samp> should be excluded. The label <code>H</code>
782    denotes a pre-processing #include statement. For example, if a source file
783    contains the line: <code>#include 'TheirHeader.h'</code>, the dependency
784    scanner will ignore it.</li>
785
786    <li><dfn>line 8</dfn>: this line declares that the external dependency for
787    <samp>ItsObject.o</samp> should be excluded. The label <code>OBJ</code>
788    denotes a compiled binary object. These dependencies are normally inserted
789    into the source files as special comments. For example, if a source file
790    contains the line: <code>! depends on: ItsObject.o</code>, the dependency
791    scanner will ignore it.</li>
792  </ul>
793
794  <p>An <code>EXCL_DEP</code> declaration normally applies to all files in the
795  build. However, you can suffix it with the name of a sub-package, i.e.
796  <code>EXCL_DEP::&lt;pcks&gt;</code>. In such case, the declaration will only
797  apply while scanning for dependencies in the source files in the sub-package
798  named &lt;pcks&gt;.</p>
799
800  <p>You can also exclude all dependency scan of a particular type. To do so,
801  simply declare the type in the value. For example, if you do not want the
802  build system to scan for the <code>CALLS: &lt;executable&gt;</code> directive
803  in the comment lines of your scripts, you can make the following
804  declaration:</p>
805  <pre>
806bld::excl_dep  EXE
807</pre>
808
809  <p>The opposite of the <code>EXCL_DEP</code> declaration is the
810  <code>DEP::&lt;pcks&gt;</code> declaration, which you can use to add a
811  dependency to a source file (in the package name <code>&lt;pcks&gt;</code>).
812  The syntax of the declaration is similar to that of <code>EXCL_DEP</code>,
813  but you must specify the package name of a source file for DEP declarations.
814  Please also note that a <code>DEP</code> declaration only works if the
815  particular dependency is supported for the particular source file - as it
816  makes no sense, for example, to specify a USE dependency for a shell
817  script.</p>
818
819  <p>If you need to switch off dependency checking completely, you can use the
820  <code>NO_DEP</code> declaration. For example, to switch off dependency
821  checking for all but the <samp>foo/bar</samp> sub-package, you can do:</p>
822  <pre>
823bld::no_dep           true
824bld::no_dep::foo/bar  false
825</pre>
826
827  <h3 id="advanced_blockdata">Linking a Fortran executable with a BLOCKDATA
828  program unit</h3>
829
830  <p>If it is required to link Fortran executables with BLOCKDATA program
831  units, you must declare the executable targets and the objects containing the
832  BLOCKDATA program units using the <code>BLOCKDATA::&lt;target&gt;</code>
833  declarations. For example, if <samp>foo.exe</samp> is an executable target
834  depending on the objects of the BLOCKDATA program units
835  <samp>blkdata.o</samp> and <samp>fbk.o</samp>, you will make the following
836  declarations:</p>
837  <pre>
838bld::blockdata::foo.exe  blkdata fbk
839</pre>
840
841  <p>If all your executables are dependent on <samp>blkdata.o</samp> and
842  <samp>fbk.o</samp>, you will make the following declarations:</p>
843  <pre>
844bld::blockdata  blkdata fbk
845</pre>
846
847  <h3 id="advanced_library">Creating library archives</h3>
848
849  <p>If you are interested in building library archives, the build system
850  allows you to do it in a relatively simple way. For each sub-package in the
851  source tree, there is a target to build a library containing all the objects
852  compiled from the source files (that are not main programs) within the
853  sub-package. If the sub-package contains children sub-packages, the object
854  files of the children will also be included recursively. By default, the
855  library archive is named after the sub-package, in the format
856  <code>lib&lt;pcks&gt;.a</code>. (For example, the library archive for the
857  package <samp>foo/bar/egg</samp> will be named
858  <samp>libfoo__bar__egg.a</samp> by default.) If you do not like the default
859  name for the sub-package library, you can use the
860  <code>LIB::&lt;pcks&gt;</code> declaration to rename it, as long as the new
861  name does not clash with other targets. For example, to rename
862  <samp>libfoo__bar__egg.a</samp> to <samp>libham.a</samp>, you will make the
863  following declaration in your extract configuration file:</p>
864  <pre>
865bld::lib::foo/bar/egg  ham
866</pre>
867
868  <p>In addition to sub-package libraries, you can also build a global library
869  archive for the whole source tree. By default, the library is named
870  <samp>libfcm_default.a</samp>, but you can rename it using the
871  <code>LIB</code> declaration as above. For example, to rename the library to
872  <samp>libmy-lib.a</samp>, you will make the following declaration in your
873  extract configuration file:</p>
874  <pre>
875bld::lib  my-lib
876</pre>
877
878  <p>When a library archive is created successfully, the build system will
879  automatically generate the relevant exclude dependency configurations in the
880  <samp>etc/</samp> sub-directory of the build root. You will be able to
881  include these configurations in subsequent builds that utilise the library.
882  The root names of the configuration files match those of the library archives
883  that you can create in the current build, but the extension <samp>*.a</samp>
884  is replaced with <samp>*.cfg</samp>. For example, the exclude dependency
885  configuration for <samp>libmy-lib.a</samp> is <samp>libmy-lib.cfg</samp>.</p>
886
887  <h3 id="advanced_pp">Pre-processing</h3>
888
889  <p>As most modern compilers can handle pre-processing, the build system
890  leaves pre-processing to the compiler by default. However, it is recognised
891  that there are code written with pre-processor directives that can alter the
892  argument list of procedures and/or their dependencies. If a source file
893  requires pre-processing in such a way, we have to pre-process before running
894  the interface block generator and the dependency scanner. The <code>PP</code>
895  declaration can be used to switch on this pre-processing stage. The
896  pre-processing stage can be switched on globally or for individual
897  sub-packages only. The following is an example, using an extract
898  configuration file:</p>
899  <pre id="example_7">
900# Example 7
901# ----------------------------------------------------------------------
902cfg::type          ext
903cfg::version       1.0
904
905bld::pp::gen       true                  # line 4
906bld::pp::var/foo   true                  # line 5
907
908bld::tool::cppkeys GOOD WEATHER FORECAST # line 7
909bld::tool::fppkeys FOO BAR EGG HAM       # line 8
910
911# ... some other declarations ...
912</pre>
913
914  <p>Here is an explanation of what each line does:</p>
915
916  <ul>
917    <li><dfn>line 4-5</dfn>: these switches on the pre-processing stage for all
918    sub-packages under <samp>gen</samp> and <samp>var/foo</samp>.</li>
919
920    <li><dfn>line 7</dfn>: this declares a list of pre-defined macros
921    <samp>GOOD</samp>, <samp>WEATHER</samp> and <samp>FORECAST</samp> for
922    pre-processing all C files.</li>
923
924    <li><dfn>line 8</dfn>: this declares a list of pre-defined macros
925    <samp>FOO</samp>, <samp>BAR</samp>, <samp>EGG</samp> and <samp>HAM</samp>
926    for pre-processing all Fortran files that require processing.</li>
927  </ul>
928
929  <p>Source files requiring pre-processing may contain <code>#include</code>
930  statements to include header files. For including a local file, its name
931  should be embedded within a pair of quotes, i.e. <samp>'file.h'</samp> or
932  <samp>"file.h"</samp>. If the header file is embedded within a pair of
933  &lt;file.h&gt; angle brackets, the system will assume that the file can be
934  found in a standard location.</p>
935
936  <p>The build system allows header files to be placed anywhere within the
937  declared source tree. The system uses the dependency scanner, as described in
938  the previous sub-section to scan for any header file dependencies. All source
939  files requiring pre-processing and all header files are scanned. Header files
940  that are required are copied to the <samp>inc/</samp> subdirectory of the
941  build root, which is automatically added to the pre-processor search path via
942  the <code>-I&lt;dir&gt;</code> option. The build system uses an internal
943  logic similar to <code>make</code> to perform pre-processing. Header files
944  are only copied to the <samp>inc/</samp> sub-directory if they are used in
945  <code>#include</code> statements.</p>
946
947  <p>Unlike <code>make</code>, which only uses the timestamp to determine
948  whether an item is out of date, the internal logic of the build system does
949  this by inspecting the content of the file as well. In an incremental build,
950  the pre-processed file is only updated if its content has changed. This
951  avoids unnecessary updates (and hence unnecessary re-compilation) in an
952  incremental build if the changed section of the code does not affect the
953  output file.</p>
954
955  <p>Pre-processed code generated during the pre-processing stage are sent to
956  the <samp>ppsrc/</samp> sub-directory of the build root. It will have a
957  relative path that reflects the name of the declared sub-package. The
958  pre-processed source file will have the same root name as the original source
959  file. For C files, the same extension <samp>.c</samp> will be used. For
960  Fortran files, the case of the extension will normally be dropped, e.g. from
961  <samp>.F90</samp> to <samp>.f90</samp>.</p>
962
963  <p>Following pre-processing, the system will use the pre-processed source
964  file as if it is the original source file. The interface generator will
965  generate the interface file using the pre-processed file, the dependency
966  scanner will scan the pre-processed file for dependencies, and the compiler
967  will compile the pre-processed source.</p>
968
969  <p>The <code>TOOL::CPPKEYS</code> and <code>TOOL::FPPKEYS</code> declarations
970  are used to pre-define macros in the C and Fortran pre-processor
971  respectively. This is implemented by the build system using the pre-processor
972  <code>-D</code> option on each word in the list. The use of these
973  declarations are not confined to the pre-process stage. If any source files
974  requiring pre-processing are left to the compiler, the declarations will be
975  used to set up the commands for compiling these source files.</p>
976
977  <p>The <code>TOOL::CPPKEYS</code> and <code>TOOL::FPPKEYS</code> declarations
978  normally applies globally, but like any other <code>TOOL</code> declarations,
979  they can be suffixed with sub-package names. In such cases, the declarations
980  will apply only to the specified sub-packages.</p>
981
982  <dl>
983    <dt>Note - changing pre-processor flags</dt>
984
985    <dd>
986      <p>As for compiler flags, the build system detects changes in
987      pre-processor flags (<code>TOOL::CPPFLAGS</code> and
988      <code>TOOL::FPPFLAGS</code>) and macro definitions
989      (<code>TOOL::CPPKEYS</code> and <code>TOOL::FPPKEYS</code>). If the
990      pre-processor flags or the macro definitions have changed in an
991      incremental build, the system will re-do all the necessary
992      pre-processing. The following hierarchy is followed:</p>
993
994      <ul>
995        <li>If the pre-processor flags or macro definitions for a particular
996        source file change, only that source file will be pre-processed
997        again.</li>
998
999        <li>If the pre-processor flags or macro definitions for a particular
1000        container package change, only source files within that container will
1001        be pre-processed again.</li>
1002
1003        <li>If the global pre-processor flags or macro definitions change, all
1004        source files will be pre-processed again.</li>
1005
1006        <li>If the pre-processor command changes, all source files are
1007        pre-processed again.</li>
1008      </ul>
1009    </dd>
1010  </dl>
1011
1012  <h3 id="advanced_file-type">File type</h3>
1013
1014  <p>The build system only knows what to do with an input source file if it
1015  knows what type of file it is. The type of a source file is normally
1016  determined automatically using one of the following three methods (in
1017  order):</p>
1018
1019  <ol>
1020    <li>If the file is named with an extension, its extension will be matched
1021    against a set of registered file extensions. If a match is found, the file
1022    type will be set according to the register.</li>
1023
1024    <li>If a file does not have an extension or does not match with a
1025    registered extension, its name is compared with a set of pre-defined
1026    patterns. If a match is found, the file type will be set according to the
1027    file type associated with the pattern.</li>
1028
1029    <li>If the above two methods failed and if the file is a text file, the
1030    system will attempt to read the first line of the file. If the first line
1031    begins with a <code>#!</code> pattern, the line will be compared with a set
1032    of pre-defined patterns. If a match is found, the file type will be set
1033    according to the file type associated with the pattern.</li>
1034  </ol>
1035
1036  <p>In addition to the above, if a file is a Fortran or C source file, the
1037  system will attempt to open the source file to determine whether it contains
1038  a main program, module (Fortran only) or just standalone procedures. All
1039  these information will be used later by the build system to process the
1040  source file.</p>
1041
1042  <p>The build system registers a file type with a set of type flags delimited
1043  by the double colons <code>::</code>. For example, a Fortran 9X source file
1044  is registered as <code>FORTRAN::FORTRAN9X::SOURCE</code>. (Please note that
1045  the order of the type flags in the list is insignificant. For example,
1046  <code>FORTRAN::SOURCE</code> is the same as <code>SOURCE::FORTRAN</code>.)
1047  For a list of all the type flags used by the build system, please see the
1048  <a href="annex_bld_cfg.html#infile-ext-types">input file extension type flags
1049  table</a> in the <a href="annex_bld_cfg.html">Annex: Declarations in FCM
1050  build configuration file</a>.</p>
1051
1052  <p>The following is a list of default input file extensions and their
1053  associated types:</p>
1054
1055  <dl>
1056    <dt><samp>.f .for .ftn .f77</samp></dt>
1057
1058    <dd><code>FORTRAN::SOURCE</code> Fortran 77 source file (assumed to be
1059    fixed format)</dd>
1060
1061    <dt><samp>.f90 .f95</samp></dt>
1062
1063    <dd><code>FORTRAN::FORTRAN9X::SOURCE</code> Fortran 9X source file (assumed
1064    to be free format)</dd>
1065
1066    <dt><samp>.F .FOR .FTN .F77</samp></dt>
1067
1068    <dd><code>FPP::SOURCE</code> Fortran 77 source file (assumed to be fixed
1069    format) that requires pre-processing</dd>
1070
1071    <dt><samp>.F90 .F95</samp></dt>
1072
1073    <dd><code>FPP::FPP9X::SOURCE</code> Fortran 9X source file (assumed to be
1074    free format) that requires pre-processing</dd>
1075
1076    <dt><samp>.c</samp></dt>
1077
1078    <dd><code>C::SOURCE</code> C source file</dd>
1079
1080    <dt><samp>.h .h90</samp></dt>
1081
1082    <dd><code>CPP::INCLUDE</code> Pre-processor <code>#include</code> header
1083    file</dd>
1084
1085    <dt><samp>.o .obj</samp></dt>
1086
1087    <dd><code>BINARY::OBJ</code> Compiled binary object</dd>
1088
1089    <dt><samp>.exe</samp></dt>
1090
1091    <dd><code>BINARY::EXE</code> Binary executable</dd>
1092
1093    <dt><samp>.a</samp></dt>
1094
1095    <dd><code>BINARY::LIB</code> Binary object library archive</dd>
1096
1097    <dt><samp>.sh .ksh .bash .csh</samp></dt>
1098
1099    <dd><code>SHELL::SCRIPT</code> Unix shell script</dd>
1100
1101    <dt><samp>.pl .pm</samp></dt>
1102
1103    <dd><code>PERL::SCRIPT</code> Perl script</dd>
1104
1105    <dt><samp>.py</samp></dt>
1106
1107    <dd><code>PYTHON::SCRIPT</code> Python script</dd>
1108
1109    <dt><samp>.tcl</samp></dt>
1110
1111    <dd><code>TCL::SCRIPT</code> Tcl/Tk script</dd>
1112
1113    <dt><samp>.pro</samp></dt>
1114
1115    <dd><code>PVWAVE::SCRIPT</code> IDL/PVWave program</dd>
1116
1117    <dt><samp>.cfg</samp></dt>
1118
1119    <dd><code>CFGFILE</code> FCM configuration file</dd>
1120
1121    <dt><samp>.inc</samp></dt>
1122
1123    <dd><code>FORTRAN::FORTRAN9X::INCLUDE</code> Fortran INCLUDE file</dd>
1124
1125    <dt><samp>.interface</samp></dt>
1126
1127    <dd><code>FORTRAN::FORTRAN9X::INCLUDE::INTERFACE</code> Fortran 9X INCLUDE
1128    interface block file</dd>
1129  </dl>
1130
1131  <p>N.B. The extension must be unique. For example, the system does not
1132  support the use of <samp>.inc</samp> files for both <code>#include</code> and
1133  Fortran <code>INCLUDE</code>.</p>
1134
1135  <p>The following is a list of supported file name patterns and their
1136  associated types:</p>
1137
1138  <dl>
1139    <dt><samp>*Scr_* *Comp_* *IF_* *Suite_* *Interface_*</samp></dt>
1140
1141    <dd><code>SHELL::SCRIPT</code> Unix shell script, GEN-based project naming
1142    conventions</dd>
1143
1144    <dt><samp>*List_*</samp></dt>
1145
1146    <dd><code>SHELL::SCRIPT::GENLIST</code> Unix shell script, GEN list
1147    file</dd>
1148
1149    <dt><samp>*Sql_*</samp></dt>
1150
1151    <dd><code>SCRIPT::SQL</code> SQL script, GEN-based project naming
1152    conventions</dd>
1153  </dl>
1154
1155  <p>The following is a list of supported <code>#!</code> line patterns and
1156  their associated types:</p>
1157
1158  <dl>
1159    <dt><samp>*sh* *ksh* *bash* *csh*</samp></dt>
1160
1161    <dd><code>SHELL::SCRIPT</code> Unix shell script</dd>
1162
1163    <dt><samp>*perl*</samp></dt>
1164
1165    <dd><code>PERL::SCRIPT</code> Perl script</dd>
1166
1167    <dt><samp>*python*</samp></dt>
1168
1169    <dd><code>PYTHON::SCRIPT</code> Python script</dd>
1170
1171    <dt><samp>*tclsh* *wish*</samp></dt>
1172
1173    <dd><code>TCL::SCRIPT</code> Tcl/Tk script</dd>
1174  </dl>
1175
1176  <p>The build system allows you to add or modify the register for input file
1177  extensions and their associated type using the
1178  <code>INFILE_EXT::&lt;ext&gt;</code> declaration, where &lt;ext&gt; is a file
1179  name extension without the leading dot. If file extension alone is
1180  insufficient for defining the type of your source file, you can use the
1181  <code>SRC_TYPE::&lt;pcks&gt;</code> declaration, (where &lt;pcks&gt; is the
1182  package name of the source file). For example, in an extract configuration
1183  file, you may have:</p>
1184  <pre id="example_8">
1185# Example 8
1186# ----------------------------------------------------------------------
1187cfg::type                ext
1188cfg::version             1.0
1189
1190bld::infile_ext::foo     CPP::INCLUDE                # line 4
1191bld::infile_ext::bar     FORTRAN::FORTRAN9X::INCLUDE # line 5
1192bld::src_type::egg/ham.f FORTRAN::FORTRAN9X::INCLUDE # line 6
1193
1194# ... some other declarations ...
1195</pre>
1196
1197  <p>Here is an explanation of what each line does:</p>
1198
1199  <ul>
1200    <li><dfn>line 4</dfn>: this line registers the extension <samp>.foo</samp>
1201    to be of type <code>CPP::INCLUDE</code>. This means that any input files
1202    with <samp>.foo</samp> extension will be treated as if they are
1203    pre-processor header files.</li>
1204
1205    <li><dfn>line 5</dfn>: this line registers the extension <samp>.bar</samp>
1206    to be of type <code>FORTRAN::FORTRAN9X::INCLUDE</code>. This means that any
1207    input file with <samp>.bar</samp> extension will be treated as if they are
1208    Fortran 9X INCLUDE files.</li>
1209
1210    <li><dfn>line 6</dfn>: this line declares the type for the source file in
1211    the package <samp>egg::ham.f</samp> to be
1212    <code>FORTRAN::FORTRAN9X::INCLUDE</code>. Without this declaration, this
1213    file would normally be given the type <code>FORTRAN::SOURCE</code>.</li>
1214  </ul>
1215
1216  <p>The <code>INFILE_EXT</code> declarations deal with extensions of input
1217  files. There is also a <code>OUTFILE_EXT::&lt;type&gt;</code> declaration
1218  that deals with extensions of output files. The declaration is opposite that
1219  of <code>INFILE_EXT</code>. The file &lt;type&gt; is now declared with the
1220  label, and the extension is declared as the value. It is worth noting that
1221  <code>OUTFILE_EXT</code> declarations use very different syntax for
1222  &lt;type&gt;, and the declared extension must include the leading dot. For a
1223  list of output types used by the build system, please see the <a href=
1224  "annex_bld_cfg.html#outfile-ext-types">output file extension types table</a>
1225  in the <a href="annex_bld_cfg.html">Annex: Declarations in FCM build
1226  configuration file</a>. An example is given below:</p>
1227  <pre id="example_9">
1228# Example 9
1229# ----------------------------------------------------------------------
1230cfg::type                   ext
1231cfg::version                1.0
1232
1233bld::outfile_ext::mod       .MOD   # line 4
1234bld::outfile_ext::interface .intfb # line 5
1235
1236# ... some other declarations ...
1237</pre>
1238
1239  <p>Here is an explanation of what each line does:</p>
1240
1241  <ul>
1242    <li><dfn>line 4</dfn>: this line modifies the extension of compiled Fortran
1243    9X module information files from the default <samp>.mod</samp> to
1244    <samp>.MOD</samp>.</li>
1245
1246    <li><dfn>line 5</dfn>: this line modifies the extension of INCLUDE Fortran
1247    9X interface block files from the default <samp>.interface</samp> to
1248    <samp>.intfb</samp>.</li>
1249  </ul>
1250
1251  <p>N.B. If you have made changes to the file type registers, whether it is
1252  for input files or output files, it is always worth re-building your code in
1253  full-build mode to avoid unexpected behaviour.</p>
1254
1255  <h3 id="advanced_inherit">Inherit from a previous build</h3>
1256
1257  <p>As you can inherit from previous extracts, you can inherit from previous
1258  builds. The very same <code>USE</code> statement can be used to declare a
1259  build, which the current build will depend on. The only difference is that
1260  the declared location must contain a valid build configuration file. In fact,
1261  if you use the extract system to obtain your build configuration file, any
1262  <code>USE</code> declarations in the extract configuration file will also be
1263  <code>USE</code> declarations in the output build configuration file.</p>
1264
1265  <p>By declaring a previous build with a <code>USE</code> statement, the
1266  current build automatically inherits settings from it. The following points
1267  are worth noting:</p>
1268
1269  <ul>
1270    <li>Build targets are not normally inherited. However, you can switch on
1271    inheritance of build targets using an <code>INHERIT::TARGET</code>
1272    declaration, such as:
1273      <pre>
1274inherit::target  true
1275</pre>
1276    </li>
1277
1278    <li>The build root directory and its sub-directories of the inherited build
1279    are placed into the search paths. For example, if we have an inherited
1280    build at <samp>/path/to/inherited</samp>, and it is used by a build at
1281    <samp>/path/to/my_build</samp>, the search path of executable files will
1282    become <samp>/path/to/my_build/bin:/path/to/inherited/bin</samp>, so that
1283    the <samp>bin/</samp> sub-directory of the current build is searched before
1284    the <samp>bin/</samp> sub-directory of the inherited build. If two or more
1285    <code>USE</code> statements are declared, the <code>USE</code> statement
1286    declared last will have higher priority. For example, if the current build
1287    is <var>C</var>, and it USEs build <var>A</var> before build <var>B</var>,
1288    the search path will be <samp>C:B:A</samp>.</li>
1289
1290    <li>Source files are inherited by default. If a source file is declared in
1291    the current build that has the same package name as a source file of the
1292    inherited build, it will override that in the inherited build. Any source
1293    files missing from the current build will be taken from the inherited
1294    build.
1295
1296      <p>You can switch off inheritance of source files using an
1297      <code>INHERIT::SRC</code> declaration. This declaration can be suffixed
1298      with the name of a sub-package. In such case, the declaration applies
1299      only to the inheritance of the sub-package. Otherwise, it applies
1300      globally. For example:</p>
1301      <pre>
1302# Switch off inheritance of source files in the <samp>gen</samp> sub-package
1303inherit::src::gen  false
1304</pre>
1305    </li>
1306
1307    <li><code>BLOCKDATA</code>, <code>DEP</code>, <code>EXCL_DEP</code>,
1308    <code>EXE_DEP</code>, <code>INFILE_EXT</code>, <code>LIB</code>,
1309    <code>OUTFILE_EXT</code>, <code>PP</code>, <code>TOOL</code> and
1310    <code>SRC_TYPE</code> declarations are automatically inherited. If the same
1311    setting is declared in the current incremental build, it overrides the
1312    inherited declaration.</li>
1313  </ul>
1314
1315  <p>As an example, suppose we have already performed an extract and build
1316  based on the configuration in <a href="#example_2">example 2</a>, we can set
1317  up an extract configuration file as follows:</p>
1318  <pre id="example_10">
1319# Example 10
1320# ----------------------------------------------------------------------
1321cfg::type            ext
1322cfg::version         1.0
1323
1324use                  $HOME/example               # line 4
1325
1326dest                 $HOME/example10             # line 6
1327
1328bld::inherit::target true                        # line 8
1329bld::target          ham.exe egg.exe             # line 9
1330
1331bld::tool::fflags    -O2 -w                      # line 11
1332bld::tool::cflags    -O2                         # line 12
1333
1334# ... and other declarations for repositories and source directories ...
1335</pre>
1336
1337  <p>Here is an explanation of what each line does:</p>
1338
1339  <ul>
1340    <li><dfn>line 4</dfn>: this line declares a previous extract at
1341    <samp>$HOME/example</samp> which the current extract will inherit from. The
1342    same line will be written to the output build configuration file. The
1343    subsequent build will then inherit from the build at
1344    <samp>$HOME/example</samp>.</li>
1345
1346    <li><dfn>line 6</dfn>: this declares the destination root directory of the
1347    current extract, which will become the root directory of the current build.
1348    Search paths of the build sub-directories will be set automatically. For
1349    example, the search path for executable files created by the current build
1350    will be <samp>$HOME/example10/bin:$HOME/example/bin</samp>.</li>
1351
1352    <li><dfn>line 8</dfn>: this line switches on inheritance of build targets.
1353    The build targets in <a href="#example_1">example 1</a>, i.e.
1354    <samp>foo.exe</samp> and <samp>bar.exe</samp> will be built as part of the
1355    current build.</li>
1356
1357    <li><dfn>line 9</dfn>: this declares two new build targets
1358    <samp>ham.exe</samp> and <samp>egg.exe</samp> to be added to the inherited
1359    ones. The default build targets of the current build will now be
1360    <samp>foo.exe</samp>, <samp>bar.exe</samp>, <samp>ham.exe</samp> and
1361    <samp>egg.exe</samp>.</li>
1362
1363    <li><dfn>line 11-12</dfn>: these lines modify options used by the Fortran
1364    and the C compilers, overriding those inherited from <a href=
1365    "#example_1">example 1</a>.</li>
1366  </ul>
1367
1368  <dl>
1369    <dt>Build inheritance limitation: handling of include files</dt>
1370
1371    <dd>
1372      <p>The build system uses the compiler/pre-processor's <code>-I</code>
1373      option to specify the search path for include files. For example, it uses
1374      the option to specify the <samp>inc/</samp> sub-directories of the
1375      current build and its inherited build.</p>
1376
1377      <p>However, some compilers/pre-processors (e.g. <code>cpp</code>) search
1378      for include files from the container directory of the source file before
1379      searching for the paths specified by the <code>-I</code> options. This
1380      behaviour may cause the build to behave incorrectly.</p>
1381
1382      <p>Consider a source file <samp>egg/hen.c</samp> that includes
1383      <samp>fried.h</samp>. If the directory structure looks like:</p>
1384      <pre>
1385# Sources in inherited build:
1386egg/hen.c
1387egg/fried.h
1388
1389# Sources in current build:
1390egg/fried.h
1391</pre>
1392
1393      <p>The system will correctly identify that <samp>fried.h</samp> is out of
1394      date, and trigger a re-compilation of <samp>egg/hen.c</samp>. However, if
1395      the compiler searches for the include files from the container directory
1396      of the source file first, it will wrongly use the include file in the
1397      inherited build instead of the current one.</p>
1398
1399      <p>Some compilers (e.g. <code>gfortran</code>) do not behave this way and
1400      others (e.g. <code>ifort</code>) have options to prevent include file
1401      search in the container directory of the source file. If you are using
1402      such a compiler you can avoid the problem for Fortran compilation
1403      although this does not fix the problem entirely if you have switched on
1404      the pre-processing stage. Otherwise you may have to work around the
1405      problem, (e.g. by making a comment change in the source file, or by not
1406      using an inherited build at all).</p>
1407    </dd>
1408  </dl>
1409
1410  <h3 id="advanced_data">Building data files</h3>
1411
1412  <p>While the usual targets to be built are the executables associated with
1413  source files containing main programs, libraries or scripts, the build system
1414  also allows you to build <em>data</em> files. All files with no registered
1415  type are considered to be <em>data</em> files. For each container
1416  sub-package, there is an automatic target for copying all <em>data</em> files
1417  to the <samp>etc/</samp> sub-directory of the build root. The name of the
1418  target has the form <code>&lt;pcks&gt;.etc</code>, where &lt;pcks&gt; is the
1419  name of the sub-package (with package names delimited by the double
1420  underscore <code>__</code>). For example, the target name for sub-package
1421  <samp>foo/bar</samp> is <samp>foo__bar.etc</samp>. This target is
1422  particularly useful for copying, say, all namelists in a sub-package to the
1423  <samp>etc/</samp> sub-directory of the build root.</p>
1424
1425  <p>At the end of a successful build, if the <samp>etc/</samp> sub-directory
1426  is not empty, the <samp>fcm_env.sh</samp> script will export the environment
1427  variable <var>FCM_ETCDIR</var> to point to the <samp>etc/</samp>
1428  sub-directory. You should be able to use this environment variable to locate
1429  your data files.</p>
1430
1431  <h2 id="verbose">Diagnostic verbose level</h2>
1432
1433  <p>The amount of diagnostic messages generated by the build system is
1434  normally set to a level suitable for normal everyday operation. This is the
1435  default diagnostic verbose level 1. If you want a minimum amount of
1436  diagnostic messages, you should set the verbose level to 0. If you want more
1437  diagnostic messages, you can set the verbose level to 2 or 3. You can modify
1438  the verbose level in two ways. The first way is to set the environment
1439  variable <var>FCM_VERBOSE</var> to the desired verbose level. The second way
1440  is to invoke the build system with the <code>-v &lt;level&gt;</code> option.
1441  (If set, the command line option overrides the environment variable.)</p>
1442
1443  <p>The following is a list of diagnostic output at each verbose level:</p>
1444
1445  <dl>
1446    <dt>Level 0</dt>
1447
1448    <dd>
1449      <ul>
1450        <li>Report the time taken at the end of each stage of the build
1451        process.</li>
1452
1453        <li>Run the <code>make</code> command in silent mode.</li>
1454      </ul>
1455    </dd>
1456
1457    <dt>Level 1</dt>
1458
1459    <dd>
1460      <ul>
1461        <li>Everything at verbose level 0.</li>
1462
1463        <li>Report the name of the build configuration file.</li>
1464
1465        <li>Report the location of the build destination.</li>
1466
1467        <li>Report date/time at the beginning of each stage of the build
1468        process.</li>
1469
1470        <li>Report removed directories.</li>
1471
1472        <li>Report number of pre-processed files.</li>
1473
1474        <li>Report number of generated F9X interface files.</li>
1475
1476        <li>Report number of source files scanned for dependencies.</li>
1477
1478        <li>Report name of updated <samp>Makefile</samp>.</li>
1479
1480        <li>Print compiler/linker commands.</li>
1481
1482        <li>Report total time.</li>
1483      </ul>
1484    </dd>
1485
1486    <dt>Level 2</dt>
1487
1488    <dd>
1489      <ul>
1490        <li>Everything at verbose level 1.</li>
1491
1492        <li>For incremental build in archive mode, report the commands used to
1493        extract the archives.</li>
1494
1495        <li>Report creation and removal of directories.</li>
1496
1497        <li>Report pre-processor commands.</li>
1498
1499        <li>Print compiler/linker commands with timestamps.</li>
1500      </ul>
1501    </dd>
1502
1503    <dt>Level 3</dt>
1504
1505    <dd>
1506      <ul>
1507        <li>Everything at verbose level 2.</li>
1508
1509        <li>Report update of dummy files.</li>
1510
1511        <li>Report all shell commands.</li>
1512
1513        <li>Report pre-processor commands with timestamps.</li>
1514
1515        <li>Report any F9X interface files generated.</li>
1516
1517        <li>Report number of lines and number of automatic dependencies for
1518        each source file which is scanned.</li>
1519
1520        <li>Run <code>make</code> on normal mode (as opposed to silent
1521        mode).</li>
1522
1523        <li>Report start date/time and time taken of <code>make</code>
1524        commands.</li>
1525      </ul>
1526    </dd>
1527  </dl>
1528
1529  <h2 id="overview">Overview of the build process</h2>
1530
1531  <p>The FCM build process can be summarised in five stages. Here is a summary
1532  of what is done in each stage:</p>
1533
1534  <ol>
1535    <li><dfn>Parse configuration and setup destination</dfn>: in this
1536    pre-requisite stage, the build system parses the configuration file. The
1537    <samp>src/</samp> sub-directory is searched recursively for source files.
1538    For full builds, it ensures that the sub-directories and files created by
1539    the build system are removed. If you invoke <code>fcm build</code> with a
1540    <code>--clean</code> option, the system will not go any further.</li>
1541
1542    <li><dfn>Setup build</dfn>: in this first stage, the system determines
1543    whether any settings have changed by using the cache. If so, the cache is
1544    updated with the current settings.</li>
1545
1546    <li><dfn>Pre-process</dfn>: if any files in any source files require
1547    pre-processing, they will be pre-processed at this stage. The resulting
1548    pre-processed source files will be sent to the <samp>ppsrc/</samp>
1549    sub-directory of the build root.</li>
1550
1551    <li><dfn>Generate dependency</dfn>: the system scans source files of
1552    registered types for dependency information. For an incremental build, the
1553    information is only updated if a source file is changed. The system then
1554    uses the information to write a <samp>Makefile</samp> for the main
1555    build.</li>
1556
1557    <li><dfn>Generate interface</dfn>: if there are Fortran 9X source files
1558    with standalone subroutines and functions, the build system generates
1559    interface blocks for them. The result of which will be written to the
1560    interface files in the <samp>inc/</samp> sub-directory of the build
1561    root.</li>
1562
1563    <li>
1564      <dfn>Make</dfn>: the system invokes <code>make</code> on the
1565      <samp>Makefile</samp> generated in the previous stage to perform the main
1566      build. Following a build, the <em>root</em> directory of the build may
1567      contain the following sub-directories (empty ones are removed
1568      automatically at the end of the build process):
1569
1570      <dl>
1571        <dt><samp>.cache/.bld/</samp></dt>
1572
1573        <dd>Cache files, used internally by FCM.</dd>
1574
1575        <dt><samp>bin/</samp></dt>
1576
1577        <dd>Executable binaries and scripts.</dd>
1578
1579        <dt><samp>cfg/</samp></dt>
1580
1581        <dd>Configuration files.</dd>
1582
1583        <dt><samp>done/</samp></dt>
1584
1585        <dd>Dummy <em>done</em> files used internally by the
1586        <samp>Makefile</samp> generated by FCM.</dd>
1587
1588        <dt><samp>etc/</samp></dt>
1589
1590        <dd>Miscellaneous data files.</dd>
1591
1592        <dt><samp>flags/</samp></dt>
1593
1594        <dd>Dummy <em>flags</em> files used internally by the
1595        <samp>Makefile</samp> generated by FCM.</dd>
1596
1597        <dt><samp>inc/</samp></dt>
1598
1599        <dd>Include files, such as <samp>*.h</samp>, <samp>*.inc</samp>,
1600        <samp>*.interface</samp>, and <samp>*.mod</samp>.</dd>
1601
1602        <dt><samp>lib/</samp></dt>
1603
1604        <dd>Object library archives.</dd>
1605
1606        <dt><samp>obj/</samp></dt>
1607
1608        <dd>Compiled object files.</dd>
1609
1610        <dt><samp>ppsrc/</samp></dt>
1611
1612        <dd>Source directories with pre-processed files.</dd>
1613
1614        <dt><samp>src/</samp></dt>
1615
1616        <dd>Source directories. This directory is not changed by the build
1617        system.</dd>
1618
1619        <dt><samp>tmp/</samp></dt>
1620
1621        <dd>Temporary objects and binaries. Files generated by the
1622        compiler/linker may be left here.</dd>
1623      </dl>
1624    </li>
1625  </ol>
1626
1627  </div>
1628  </div>
1629  </div>
1630
1631  <hr/>
1632  <div class="container-fluid text-center">
1633    <div class="row"><div class="col-md-12">
1634    <address><small>
1635      Copyright &copy; 2006-2021 British Crown (Met Office) &amp; Contributors.
1636      <a href="http://www.metoffice.gov.uk">Met Office</a>.
1637      See <a href="../etc/fcm-terms-of-use.html">Terms of Use</a>.<br />
1638      This document is released under the British <a href=
1639      "http://www.nationalarchives.gov.uk/doc/open-government-licence/" rel=
1640      "license">Open Government Licence</a>.<br />
1641    </small></address>
1642    </div></div>
1643  </div>
1644
1645  <script type="text/javascript" src="../etc/jquery.min.js"></script>
1646  <script type="text/javascript" src="../etc/bootstrap/js/bootstrap.min.js"></script>
1647  <script type="text/javascript" src="../etc/fcm.js"></script>
1648  <script type="text/javascript" src="../etc/fcm-version.js"></script>
1649</body>
1650</html>
Note: See TracBrowser for help on using the repository browser.