New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
build.html in vendors/fcm/current/doc/user_guide – NEMO

source: vendors/fcm/current/doc/user_guide/build.html @ 1977

Last change on this file since 1977 was 1977, checked in by flavoni, 14 years ago

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